framework-py 0.1.0.dev1__tar.gz → 0.1.0.dev2__tar.gz

{framework_py-0.1.0.dev1 → framework_py-0.1.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: framework-py
-Version: 0.1.0.dev1
+Version: 0.1.0.dev2
 Summary: Structured data science projects: a data catalog, integrity tracking, caching, outputs, and AI guardrails
 Project-URL: Homepage, https://framework.pub
 Project-URL: Source, https://github.com/frameworktools/framework-py

{framework_py-0.1.0.dev1 → framework_py-0.1.0.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "framework-py"
-version = "0.1.0.dev1"
+version = "0.1.0.dev2"
 description = "Structured data science projects: a data catalog, integrity tracking, caching, outputs, and AI guardrails"
 readme = "README.md"
 license = "MIT"
@@ -85,7 +85,7 @@ strict = true
 files = ["src", "scripts"]
 
 [[tool.mypy.overrides]]
-module = ["pyarrow", "pyarrow.*", "keyring", "keyring.*", "secretstorage", "matplotlib", "matplotlib.*", "openpyxl", "pyreadstat", "boto3", "botocore", "botocore.*", "pyodbc", "pymysql", "psycopg", "psycopg.*", "duckdb"]
+module = ["pyarrow", "pyarrow.*", "keyring", "keyring.*", "secretstorage", "jsonschema", "matplotlib", "matplotlib.*", "openpyxl", "pyreadstat", "boto3", "botocore", "botocore.*", "pyodbc", "pymysql", "psycopg", "psycopg.*", "duckdb"]
 ignore_missing_imports = true
 
 [tool.pytest.ini_options]

framework_py-0.1.0.dev2/scripts/build_docs.py

@@ -0,0 +1,377 @@
+"""Build the docs site archive for py.framework.pub.
+
+Writes ``reference.json`` from the docstrings of everything in
+``framework.__all__``, checks it against ``docs-reference.v1.json``, and
+packs ``docs/site`` with it into ``docs-site.tar.gz``. The format is R's
+``inst/schema/docs-site.md``.
+
+    python scripts/build_docs.py                        # check only
+    python scripts/build_docs.py --reference out.json   # write reference.json
+    python scripts/build_docs.py --archive dist-docs/docs-site.tar.gz
+
+Docstrings are Google style. The first line is the summary, the paragraphs
+before the first section are the description, and ``Args:`` (or
+``Attributes:`` for classes), ``Returns:``, and ``Raises:`` become
+parameters, returns, and a section.
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import inspect
+import io
+import json
+import re
+import sys
+import tarfile
+from pathlib import Path
+from typing import Any
+
+import jsonschema
+import yaml
+
+import framework
+
+ROOT = Path(__file__).resolve().parents[1]
+SITE = ROOT / "docs" / "site"
+SCHEMA = ROOT / "src" / "framework" / "_assets" / "schema" / "docs-reference.v1.json"
+
+_SECTION = re.compile(r"^(Args|Arguments|Attributes|Returns|Yields|Raises|Examples?|Notes?):\s*$")
+_ITEM = re.compile(r"^(\*{0,2}[A-Za-z_][A-Za-z0-9_]*)(?:\s*\(([^)]*)\))?:\s*(.*)$")
+
+
+class DocsError(Exception):
+    pass
+
+
+# Docstrings -------------------------------------------------------------------
+
+
+def _markdown(text: str) -> str:
+    """reStructuredText inline code to Markdown, linking exported names."""
+    exported = set(framework.__all__)
+
+    def code(match: re.Match[str]) -> str:
+        inner = match.group(1)
+        name = inner.removesuffix("()")
+        if name in exported:
+            return f"[`{inner}`](ref:{name})"
+        return f"`{inner}`"
+
+    return re.sub(r"``(.+?)``", code, text).strip()
+
+
+def _dedent_block(lines: list[str]) -> list[str]:
+    indents = [len(line) - len(line.lstrip()) for line in lines if line.strip()]
+    cut = min(indents, default=0)
+    return [line[cut:] for line in lines]
+
+
+def parse_docstring(doc: str) -> dict[str, Any]:
+    """Split a Google-style docstring into summary, description, and sections."""
+    lines = doc.strip().splitlines()
+    summary = lines[0].strip() if lines else ""
+    body: list[str] = []
+    sections: dict[str, list[str]] = {}
+    current: list[str] = body
+    for line in lines[1:]:
+        match = _SECTION.match(line)
+        if match:
+            key = {"Arguments": "Args", "Example": "Examples", "Notes": "Note"}.get(
+                match.group(1), match.group(1)
+            )
+            current = sections.setdefault(key, [])
+            continue
+        current.append(line)
+    paragraphs = re.split(r"\n\s*\n", "\n".join(body).strip())
+    paragraphs = [p for p in paragraphs if p.strip()]
+    return {
+        "summary": summary,
+        "description": "\n\n".join(paragraphs[:2]),
+        "details": "\n\n".join(paragraphs[2:]),
+        "sections": {key: _dedent_block(value) for key, value in sections.items()},
+    }
+
+
+def parse_items(lines: list[str]) -> list[tuple[str, str]]:
+    """``name: text`` items, with indented continuation lines folded in."""
+    items: list[tuple[str, list[str]]] = []
+    for line in lines:
+        if not line.strip():
+            if items:
+                items[-1][1].append("")
+            continue
+        match = _ITEM.match(line) if not line.startswith(" ") else None
+        if match:
+            items.append((match.group(1), [match.group(3)]))
+        elif items:
+            items[-1][1].append(line.strip())
+    return [
+        (name, re.sub(r"(?<!\n)\n(?!\n)", " ", "\n".join(text).strip())) for name, text in items
+    ]
+
+
+# Entries ----------------------------------------------------------------------
+
+
+def _annotation(value: Any) -> str | None:
+    if value is inspect.Parameter.empty:
+        return None
+    return value if isinstance(value, str) else str(inspect.formatannotation(value))
+
+
+def _prefix(param: inspect.Parameter) -> str:
+    if param.kind is inspect.Parameter.VAR_POSITIONAL:
+        return "*"
+    if param.kind is inspect.Parameter.VAR_KEYWORD:
+        return "**"
+    return ""
+
+
+def _parameter(param: inspect.Parameter) -> str:
+    """A parameter as written in the source, shortening long defaults."""
+    text = _prefix(param) + param.name
+    annotation = _annotation(param.annotation)
+    if annotation:
+        text += f": {annotation}"
+    if param.default is not param.empty:
+        default = repr(param.default)
+        if len(default) > 30:
+            default = f"{default[0]}...{default[-1]}" if default[0] in "([{" else "..."
+        text += f" = {default}" if annotation else f"={default}"
+    return text
+
+
+def _usage(name: str, signature: inspect.Signature) -> str:
+    params: list[str] = []
+    for param in signature.parameters.values():
+        if param.name == "self":
+            continue
+        if param.kind == param.KEYWORD_ONLY and not any(p.startswith("*") for p in params):
+            params.append("*")
+        params.append(_parameter(param))
+    returns = _annotation(signature.return_annotation)
+    tail = f" -> {returns}" if returns else ""
+    one_line = f"{name}({', '.join(params)}){tail}"
+    if len(one_line) <= 88:
+        return one_line
+    inner = "".join(f"    {p},\n" for p in params)
+    return f"{name}(\n{inner}){tail}"
+
+
+def _signature(obj: Any) -> inspect.Signature | None:
+    try:
+        return inspect.signature(obj)
+    except (TypeError, ValueError):
+        return None
+
+
+def build_entry(name: str, obj: Any, category: str, problems: list[str]) -> dict[str, Any]:
+    doc = inspect.getdoc(obj)
+    if not doc:
+        raise DocsError(f"{name} has no docstring")
+    parsed = parse_docstring(doc)
+    sections = parsed["sections"]
+    is_class = inspect.isclass(obj)
+    entry: dict[str, Any] = {
+        "id": name,
+        "name": name,
+        "kind": "class" if is_class else "function",
+        "category": category,
+        "summary": _markdown(parsed["summary"]),
+    }
+    for key in ("description", "details"):
+        if parsed[key]:
+            entry[key] = _markdown(parsed[key])
+
+    documented = dict(parse_items(sections.get("Attributes" if is_class else "Args", [])))
+    parameters: list[dict[str, Any]] = []
+    if is_class and dataclasses.is_dataclass(obj):
+        for field in dataclasses.fields(obj):
+            if field.name.startswith("_"):
+                continue
+            if field.name not in documented:
+                problems.append(f"{name}: attribute '{field.name}' is not documented")
+            item: dict[str, Any] = {
+                "name": field.name,
+                "description": _markdown(documented.get(field.name, "")),
+            }
+            if _annotation(field.type):
+                item["type"] = _annotation(field.type)
+            parameters.append(item)
+    elif not is_class:
+        signature = _signature(obj)
+        if signature is None:
+            raise DocsError(f"{name}: no signature")
+        entry["usage"] = _usage(name, signature)
+        for param in signature.parameters.values():
+            key = _prefix(param)
+            label = f"{key}{param.name}"
+            text = documented.get(label) or documented.get(param.name)
+            if text is None:
+                problems.append(f"{name}: parameter '{param.name}' is not documented")
+            item = {"name": label, "description": _markdown(text or "")}
+            if _annotation(param.annotation):
+                item["type"] = _annotation(param.annotation)
+            if param.default is not param.empty:
+                item["default"] = repr(param.default)
+            elif key == "":
+                item["required"] = True
+            parameters.append(item)
+    if parameters:
+        entry["parameters"] = parameters
+
+    for key in ("Returns", "Yields"):
+        if key in sections:
+            entry["returns"] = _markdown("\n".join(sections[key]))
+    if "Note" in sections:
+        entry["note"] = _markdown("\n".join(sections["Note"]))
+    if "Raises" in sections:
+        raises = "\n".join(
+            f"- `{error}`: {_markdown(text)}" for error, text in parse_items(sections["Raises"])
+        )
+        entry["sections"] = [{"title": "Raises", "content": raises}]
+    if "Examples" in sections:
+        code = "\n".join(sections["Examples"]).strip()
+        code = "\n".join(re.sub(r"^(>>> |\.\.\. )", "", line) for line in code.splitlines())
+        entry["examples"] = [{"code": code}]
+    return entry
+
+
+def build_reference(categories: list[dict[str, Any]], problems: list[str]) -> dict[str, Any]:
+    exported = list(framework.__all__)
+    placed: dict[str, str] = {}
+    for category in categories:
+        for name in category["names"]:
+            if name in placed:
+                raise DocsError(f"{name} is in both {placed[name]} and {category['id']}")
+            placed[name] = category["id"]
+        for name in category.get("common", []):
+            if name not in category["names"]:
+                raise DocsError(f"{category['id']}: common name {name} is not in its names")
+    documented = [name for name in exported if not name.startswith("__")]
+    missing = sorted(set(documented) - set(placed))
+    unknown = sorted(set(placed) - set(documented))
+    if missing or unknown:
+        raise DocsError(
+            f"categories.yml: missing {missing or 'none'}; not exported {unknown or 'none'}"
+        )
+    entries = [
+        build_entry(name, getattr(framework, name), placed[name], problems)
+        for category in categories
+        for name in category["names"]
+    ]
+    return {
+        "schema": "docs-reference.v1",
+        "product": "py",
+        "version": framework.__version__,
+        "categories": [
+            {
+                key: value
+                for key, value in {
+                    "id": category["id"],
+                    "title": category["title"],
+                    "description": category.get("description"),
+                    "position": position,
+                    "common": category.get("common"),
+                }.items()
+                if value is not None
+            }
+            for position, category in enumerate(categories, start=1)
+        ],
+        "entries": entries,
+    }
+
+
+# Site -------------------------------------------------------------------------
+
+
+def _prose(markdown: str) -> str:
+    """Markdown without fenced code blocks, whose lines are not headings or links."""
+    return re.sub(r"^(```|~~~).*?^\1[ \t]*$", "", markdown, flags=re.M | re.S)
+
+
+def check_site(reference: dict[str, Any]) -> list[str]:
+    """Check site.yml, the guides' front matter, and every guide:/ref: link."""
+    problems: list[str] = []
+    site = yaml.safe_load((SITE / "site.yml").read_text(encoding="utf-8"))
+    sections = {section["id"] for section in site["sections"]}
+    guides: dict[str, Path] = {}
+    for path in sorted((SITE / "guides").glob("*.md")):
+        text = path.read_text(encoding="utf-8")
+        match = re.match(r"\A---\n(.*?)\n---\n", text, re.S)
+        if not match:
+            problems.append(f"{path.name}: no front matter")
+            continue
+        meta = yaml.safe_load(match.group(1)) or {}
+        for key in ("id", "title", "description", "section", "position"):
+            if key not in meta:
+                problems.append(f"{path.name}: front matter is missing {key}")
+        if meta.get("section") not in sections:
+            problems.append(f"{path.name}: unknown section {meta.get('section')}")
+        if meta.get("id") != path.stem:
+            problems.append(f"{path.name}: id {meta.get('id')} does not match the file name")
+        if re.search(r"^# ", _prose(text[match.end() :]), re.M):
+            problems.append(f"{path.name}: guides have no h1")
+        guides[path.stem] = path
+    ids = {entry["id"] for entry in reference["entries"]}
+    texts = [(path.name, _prose(path.read_text(encoding="utf-8"))) for path in guides.values()]
+    texts.append(("reference.json", json.dumps(reference)))
+    for source, text in texts:
+        for kind, target in re.findall(r"\((guide|ref):([^)#\s]+)", text):
+            if kind == "guide" and target not in guides:
+                problems.append(f"{source}: no guide {target}")
+            if kind == "ref" and target not in ids:
+                problems.append(f"{source}: no reference entry {target}")
+        for image in re.findall(r"\]\((images/[^)\s]+)\)", text):
+            if not (SITE / image).is_file():
+                problems.append(f"{source}: missing {image}")
+    return problems
+
+
+def write_archive(reference: dict[str, Any], target: Path) -> None:
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with tarfile.open(target, "w:gz") as archive:
+        for path in sorted(SITE.rglob("*")):
+            if path.is_file() and path.name != "categories.yml":
+                archive.add(path, arcname=f"docs-site/{path.relative_to(SITE).as_posix()}")
+        data = (json.dumps(reference, indent=2, ensure_ascii=False) + "\n").encode("utf-8")
+        info = tarfile.TarInfo("docs-site/reference.json")
+        info.size = len(data)
+        archive.addfile(info, io.BytesIO(data))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    parser.add_argument("--reference", type=Path, help="write reference.json here")
+    parser.add_argument("--archive", type=Path, help="write docs-site.tar.gz here")
+    parser.add_argument("--schema", type=Path, default=SCHEMA, help="docs-reference.v1.json")
+    args = parser.parse_args(argv)
+    problems: list[str] = []
+    try:
+        categories = yaml.safe_load((SITE / "categories.yml").read_text(encoding="utf-8"))
+        reference = build_reference(categories, problems)
+    except DocsError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+    schema = json.loads(args.schema.read_text(encoding="utf-8"))
+    errors = sorted(
+        jsonschema.Draft202012Validator(schema).iter_errors(reference), key=lambda e: e.path
+    )
+    problems += [f"reference.json: {list(e.path)}: {e.message}" for e in errors]
+    problems += check_site(reference)
+    if problems:
+        print("\n".join(f"error: {problem}" for problem in problems), file=sys.stderr)
+        return 1
+    if args.reference:
+        args.reference.write_text(json.dumps(reference, indent=2, ensure_ascii=False) + "\n")
+    if args.archive:
+        write_archive(reference, args.archive)
+    guides = len(list((SITE / "guides").glob("*.md")))
+    print(f"{len(reference['entries'])} reference entries and {guides} guides are valid")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{framework_py-0.1.0.dev1 → framework_py-0.1.0.dev2}/scripts/sync_assets.py

@@ -28,6 +28,8 @@ WORKTREE = "worktree"
 # Runtime files go in the package; test-only files go in tests/shared.
 ASSETS: dict[str, str] = {
     "inst/schema/*.json": "src/framework/_assets/schema",
+    # The docs site format (docs/site, scripts/build_docs.py).
+    "inst/schema/docs-site.md": "docs",
     "inst/templates/init.sql": "src/framework/_assets",
     "inst/hooks/pre-commit": "src/framework/_assets/hooks",
     "inst/conformance/README.md": "tests/shared/conformance",

{framework_py-0.1.0.dev1 → framework_py-0.1.0.dev2}/src/framework/__main__.py

@@ -37,7 +37,12 @@ def _parser() -> argparse.ArgumentParser:
     create.add_argument(
         "--interactive",
         action="store_true",
-        help="prompt for missing answers, initialize git, and register the project",
+        help=(
+            "with --name, ask for the type when --type is missing (the project is "
+            "registered and gets a git repository either way, unless your defaults turn "
+            "git off); with --from-layers, initialize git and register the project "
+            "instead of running headless"
+        ),
     )
 
     bootstrap = commands.add_parser("bootstrap", help="prepare a cloned project")

{framework_py-0.1.0.dev1 → framework_py-0.1.0.dev2}/src/framework/_assets/hooks/pre-commit

@@ -12,23 +12,31 @@ set -u
 
 cd "$(git rev-parse --show-toplevel)" || exit 1
 
+# Each runner returns 127 when its runtime or the framework package is
+# missing, so the next runtime gets a turn and the message below can say why
+
 run_r() {
   command -v Rscript >/dev/null 2>&1 || return 127
+  # framework 1.x from CRAN has no shared hook entry point
+  probe='ok <- requireNamespace("framework", quietly = TRUE) && exists(".hook_run", envir = asNamespace("framework"))'
+  Rscript -e "$probe; quit(status = if (ok) 0 else 127)" >/dev/null 2>&1 || return 127
   Rscript -e 'quit(status = framework:::.hook_run("pre-commit"))'
 }
 
 run_python() {
   if [ -x .venv/bin/python ]; then
-    .venv/bin/python -m framework hook pre-commit
+    set -- .venv/bin/python
   elif [ -x .venv/Scripts/python.exe ]; then
-    .venv/Scripts/python.exe -m framework hook pre-commit
+    set -- .venv/Scripts/python.exe
   elif [ -f uv.lock ] && command -v uv >/dev/null 2>&1; then
-    uv run --frozen python -m framework hook pre-commit
+    set -- uv run --frozen python
   elif command -v python3 >/dev/null 2>&1; then
-    python3 -m framework hook pre-commit
+    set -- python3
   else
     return 127
   fi
+  "$@" -c 'import framework' >/dev/null 2>&1 || return 127
+  "$@" -m framework hook pre-commit
 }
 
 has_rproj() {
@@ -52,8 +60,8 @@ if [ "$status" -eq 127 ] && { [ -f pyproject.toml ] || [ -f uv.lock ] || [ -d .v
 fi
 
 if [ "$status" -eq 127 ]; then
-  echo "Framework hook: no R or Python runtime with framework installed was found." >&2
-  echo "Install one, or run 'git commit --no-verify' if you are sure this commit is safe." >&2
+  echo "Framework hook: found neither R with framework 2.0 or later nor Python with framework-py." >&2
+  echo "Install one of them, or run 'git commit --no-verify' if you are sure this commit is safe." >&2
   exit 1
 fi
 exit "$status"

framework_py-0.1.0.dev2/src/framework/_assets/schema/docs-reference.v1.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://framework.pub/schema/docs-reference.v1.json",
+  "title": "Framework docs reference",
+  "description": "The generated function or command reference for one product's docs site (docs/site/reference.json). Text fields hold CommonMark with GFM tables.",
+  "type": "object",
+  "required": ["schema", "product", "version", "categories", "entries"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": { "const": "docs-reference.v1" },
+    "product": { "enum": ["r", "py", "cli"] },
+    "version": { "type": "string", "minLength": 1, "description": "The release this reference was built from, such as 2.0.0 or 0.1.0.dev1." },
+    "categories": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/category" }
+    },
+    "entries": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/entry" }
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$",
+      "description": "URL-safe and unique within the product: /reference/{id}."
+    },
+    "markdown": { "type": "string" },
+    "category": {
+      "type": "object",
+      "required": ["id", "title", "position"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "title": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "description": "One line, shown under the title in the Reference dropdown." },
+        "position": { "type": "integer" },
+        "common": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Entry names listed first, under a Common heading."
+        }
+      }
+    },
+    "titled": {
+      "type": "object",
+      "required": ["title", "content"],
+      "additionalProperties": false,
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "content": { "$ref": "#/$defs/markdown" }
+      }
+    },
+    "entry": {
+      "type": "object",
+      "required": ["id", "name", "kind", "category", "summary"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "name": { "type": "string", "minLength": 1, "description": "As users write it: data_read, AuditResult, or \"project bootstrap\"." },
+        "kind": { "enum": ["function", "class", "command"] },
+        "category": { "type": "string", "description": "A category id." },
+        "title": { "type": "string", "description": "A short heading. Defaults to name." },
+        "summary": { "type": "string", "minLength": 1, "description": "One line, used in lists and search results." },
+        "usage": { "type": "string", "description": "The signature or command line, shown as code." },
+        "description": { "$ref": "#/$defs/markdown", "description": "A paragraph or two (roxygen @description, a docstring's opening paragraphs)." },
+        "details": { "$ref": "#/$defs/markdown", "description": "The long body (roxygen @details)." },
+        "parameters": {
+          "type": "array",
+          "description": "Arguments, flags, or a class's fields, in signature order.",
+          "items": {
+            "type": "object",
+            "required": ["name", "description"],
+            "additionalProperties": false,
+            "properties": {
+              "name": { "type": "string", "minLength": 1, "description": "x, *, --path, or -p, --path." },
+              "type": { "type": "string" },
+              "default": { "type": "string", "description": "As code, such as NULL, None, or \".\"." },
+              "required": { "type": "boolean" },
+              "env": { "type": "string", "description": "An environment variable that sets it (commands)." },
+              "description": { "$ref": "#/$defs/markdown" }
+            }
+          }
+        },
+        "returns": { "$ref": "#/$defs/markdown" },
+        "note": { "$ref": "#/$defs/markdown" },
+        "sections": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["title", "content"],
+            "additionalProperties": false,
+            "properties": {
+              "title": { "type": "string", "minLength": 1 },
+              "content": { "$ref": "#/$defs/markdown" },
+              "subsections": { "type": "array", "items": { "$ref": "#/$defs/titled" } }
+            }
+          }
+        },
+        "examples": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["code"],
+            "additionalProperties": false,
+            "properties": {
+              "title": { "type": "string" },
+              "code": { "type": "string", "minLength": 1 },
+              "runnable": { "type": "boolean", "default": true, "description": "False for R's \\dontrun and for examples that need a server or credentials." }
+            }
+          }
+        },
+        "see_also": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              { "type": "string", "minLength": 1, "description": "An entry name in this product, or a link target such as py:ref:data_read." },
+              {
+                "type": "object",
+                "required": ["title", "url"],
+                "additionalProperties": false,
+                "properties": {
+                  "title": { "type": "string", "minLength": 1 },
+                  "url": { "type": "string", "pattern": "^https://" }
+                }
+              }
+            ]
+          }
+        },
+        "aliases": { "type": "array", "items": { "type": "string" } },
+        "lifecycle": { "enum": ["stable", "deprecated", "experimental"], "default": "stable" },
+        "replaced_by": { "type": "string", "description": "The entry name to use instead, for deprecated entries." },
+        "since": { "type": "string", "description": "The version that added it." }
+      }
+    }
+  }
+}

{framework_py-0.1.0.dev1 → framework_py-0.1.0.dev2}/src/framework/_paths.py

@@ -2,11 +2,21 @@
 
 from __future__ import annotations
 
+import re
 from pathlib import Path
 from typing import Any
 
 from framework.project import project_root
 
+# A folder named like private, confidential, or sensitive (outputs_private and
+# private_raw count too), as the git security audit and R's audit match them.
+PRIVATE_SEGMENT = re.compile(r"(^|/)[^/]*(private|confidential|sensitive)[^/]*(/|$)", re.IGNORECASE)
+
+
+def has_private_segment(path: str | Path) -> bool:
+    """Whether a folder path, with ``/`` separators, has a private segment."""
+    return bool(PRIVATE_SEGMENT.search(Path(path).as_posix()))
+
 
 def relative_to_root(path: Path, root: Path) -> str:
     """``path`` relative to the project root when it is inside it, else absolute."""

{framework_py-0.1.0.dev1 → framework_py-0.1.0.dev2}/src/framework/ai.py

@@ -179,13 +179,16 @@ def ai_skills_update(project_path: str | Path = ".") -> list[str]:
     come from ``.framework/spec.json``, or from the settings for projects
     without one.
 
+    Args:
+        project_path: The project's root directory. Default: the current directory.
+
     Returns:
         The skill folders written.
     """
     from framework._log import inform, show_messages
 
     show_messages()
-    root = Path(project_path)
+    root = Path(project_path).expanduser()
     spec = _installed_spec(root)
     folders, _ = assistant_targets(spec)
     updated = []