commitguardian 0.1.0__py3-none-any.whl

commitguard/research/platform.py

@@ -0,0 +1,288 @@
+"""A portable validation of the local enforcement path on this machine.
+
+Designed to run unchanged on Linux, macOS and Windows (GitHub Actions runners
+for the latter two), so the compatibility matrix is built from observed results
+rather than from what should work. Every check records what was expected and
+what was observed; a check that could not run is ``SKIPPED`` with the reason,
+never ``PASS``.
+
+The repository lives in a directory whose path contains spaces and non-ASCII
+characters, because path handling is where Git hooks most often break across
+platforms.
+"""
+
+import os
+import platform as platform_module
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict
+
+from commitguard.git.hooks import (
+    HookState,
+    HookStatus,
+    HookType,
+    hook_status,
+    install_hooks,
+    repository_hooks_dir,
+    uninstall_hooks,
+)
+from commitguard.git.repository import Repository
+from commitguard.research.gitenv import Workspace, workspace
+from commitguard.utils.subprocess import run_command
+
+BENCHMARK_VERSION = "1.0.0"
+Status = Literal["PASS", "FAIL", "SKIPPED"]
+
+CLEAN = "feat: add session rotation\n\nSigned-off-by: Ada Lovelace <ada@example.com>\n"
+AI = "feat: add payment service\n\nCo-authored-by: Claude <noreply@anthropic.com>\n"
+
+
+class Check(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    area: str
+    name: str
+    status: Status
+    expected: str
+    observed: str
+
+
+class PlatformResult(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    benchmark: str = "platform"
+    benchmark_version: str = BENCHMARK_VERSION
+    system: str
+    shell_for_hooks: str
+    checks: tuple[Check, ...]
+    passed: int
+    failed: int
+    skipped: int
+
+
+def _statuses(repository: Repository) -> list[HookStatus]:
+    directory = repository_hooks_dir(repository)
+    return [hook_status(directory, hook, expected_python=sys.executable) for hook in HookType]
+
+
+def _cli(space: Workspace, cwd: Path, *args: str) -> tuple[int, str]:
+    result = run_command(
+        [sys.executable, "-P", "-m", "commitguard", *args],
+        cwd=cwd,
+        env_overrides={**space.env, "PYTHONIOENCODING": "utf-8"},
+        timeout=300,
+    )
+    output = (result.stdout + result.stderr).decode("utf-8", "replace")
+    return result.returncode, output[-300:]
+
+
+def run_platform() -> PlatformResult:
+    checks: list[Check] = []
+
+    def record(area: str, name: str, expected: str, probe: Callable[[], tuple[bool, str]]) -> bool:
+        try:
+            ok, observed = probe()
+        except Exception as exc:  # noqa: BLE001 - a failing probe is a FAIL, not a crash
+            ok, observed = False, f"{type(exc).__name__}: {exc}"[:300]
+        checks.append(
+            Check(
+                area=area,
+                name=name,
+                status="PASS" if ok else "FAIL",
+                expected=expected,
+                observed=observed,
+            )
+        )
+        return ok
+
+    with workspace() as space:
+        record(
+            "environment",
+            "git is available",
+            "git --version succeeds",
+            lambda: (
+                (r := space.git(space.root, "--version", check=False)).returncode == 0,
+                r.stdout.decode("utf-8", "replace").strip(),
+            ),
+        )
+        base = space.root / "path with spaces" / "répertoire-ünïcøde"
+        base.mkdir(parents=True)
+        remote = space.init("remote.git", bare=True)
+        space.git(base.parent, "init", "--quiet", str(base))
+        path = base
+        space.git(path, "remote", "add", "origin", str(remote))
+        space.git(path, "commit", "--quiet", "--allow-empty", "--no-verify", "-m", "chore: init")
+        space.git(path, "push", "--quiet", "--no-verify", "origin", "main")
+        repository = Repository.discover(path)
+
+        installed = record(
+            "hooks",
+            "install hooks (path with spaces and non-ASCII characters)",
+            "pre-commit, commit-msg and pre-push installed",
+            lambda: (
+                all(
+                    r.action.value in ("installed", "updated", "unchanged")
+                    for r in install_hooks(repository, python=sys.executable)
+                ),
+                ", ".join(f"{s.hook.value}={s.state.value}" for s in _statuses(repository)),
+            ),
+        )
+        if installed:
+            record(
+                "hooks",
+                "hook integrity",
+                "every hook reports installed",
+                lambda: (
+                    all(s.state is HookState.INSTALLED for s in _statuses(repository)),
+                    ", ".join(f"{s.hook.value}={s.state.value}" for s in _statuses(repository)),
+                ),
+            )
+
+        def head() -> str:
+            return space.git(path, "rev-parse", "HEAD").stdout.decode().strip()
+
+        def commit_probe(
+            message: str, *extra: str, allowed: bool
+        ) -> Callable[[], tuple[bool, str]]:
+            def probe() -> tuple[bool, str]:
+                before = head()
+                result = space.git(
+                    path, "commit", "--quiet", "--allow-empty", *extra, "-m", message, check=False
+                )
+                created = head() != before
+                ok = (
+                    (result.returncode == 0 and created)
+                    if allowed
+                    else (result.returncode != 0 and not created)
+                )
+                return (
+                    ok,
+                    f"exit {result.returncode}, commit {'created' if created else 'not created'}",
+                )
+
+            return probe
+
+        record(
+            "pre-commit / commit-msg",
+            "clean commit allowed",
+            "exit 0, commit created",
+            commit_probe(CLEAN, allowed=True),
+        )
+        record(
+            "pre-commit / commit-msg",
+            "AI co-authored commit blocked",
+            "non-zero exit, no commit",
+            commit_probe(AI, allowed=False),
+        )
+        record(
+            "bypass",
+            "git commit --no-verify skips local hooks",
+            "exit 0, commit created (documented limitation)",
+            commit_probe(AI, "--no-verify", allowed=True),
+        )
+
+        def push_probe(
+            message: str, branch: str, *extra: str, allowed: bool
+        ) -> Callable[[], tuple[bool, str]]:
+            def probe() -> tuple[bool, str]:
+                space.git(path, "checkout", "--quiet", "-B", branch, "origin/main")
+                space.git(path, "commit", "--quiet", "--allow-empty", "--no-verify", "-m", message)
+                result = space.git(path, "push", "--quiet", *extra, "origin", branch, check=False)
+                ok = result.returncode == 0 if allowed else result.returncode != 0
+                return ok, f"exit {result.returncode}"
+
+            return probe
+
+        record("pre-push", "clean push allowed", "exit 0", push_probe(CLEAN, "clean", allowed=True))
+        record(
+            "pre-push",
+            "AI co-authored push blocked",
+            "non-zero exit",
+            push_probe(AI, "ai", allowed=False),
+        )
+        record(
+            "bypass",
+            "git push --no-verify skips pre-push",
+            "exit 0 (documented limitation)",
+            push_probe(AI, "ai-bypass", "--no-verify", allowed=True),
+        )
+
+        space.git(path, "checkout", "--quiet", "clean")
+        record(
+            "cli",
+            "commitguard scan on a clean commit",
+            "exit 0",
+            lambda: ((r := _cli(space, path, "scan", "HEAD"))[0] == 0, f"exit {r[0]}"),
+        )
+        space.git(path, "checkout", "--quiet", "ai")
+        record(
+            "cli",
+            "commitguard scan on an AI co-authored commit",
+            "exit 1 (blocked)",
+            lambda: ((r := _cli(space, path, "scan", "HEAD"))[0] == 1, f"exit {r[0]}"),
+        )
+        config = path / ".commitguard.yaml"
+        config.write_bytes(b"version: 1\r\npolicies:\r\n  bot_identity:\r\n    action: block\r\n")
+        record(
+            "configuration",
+            "configuration with CRLF line endings",
+            "exit 1 (valid configuration, AI commit still blocked)",
+            lambda: ((r := _cli(space, path, "scan", "HEAD"))[0] == 1, f"exit {r[0]}"),
+        )
+        config.write_text("version: 1\npolicies: [not, a, mapping]\n", encoding="utf-8")
+        record(
+            "configuration",
+            "invalid configuration fails closed",
+            "exit 2 (error), never exit 0",
+            lambda: ((r := _cli(space, path, "scan", "HEAD"))[0] == 2, f"exit {r[0]}"),
+        )
+        config.unlink()
+        record(
+            "cli",
+            "commitguard check --message-file",
+            "exit 1 for an AI co-authored message",
+            lambda: _message_file_check(space, path),
+        )
+        record(
+            "hooks",
+            "uninstall removes the hooks",
+            "hooks absent; an AI commit is no longer blocked locally",
+            lambda: _uninstall_probe(space, path, repository),
+        )
+
+    passed = sum(1 for c in checks if c.status == "PASS")
+    failed = sum(1 for c in checks if c.status == "FAIL")
+    return PlatformResult(
+        system=(
+            f"{platform_module.system()} {platform_module.release()} ({platform_module.machine()})"
+        ),
+        shell_for_hooks="Git's sh (Git for Windows ships one)" if os.name == "nt" else "/bin/sh",
+        checks=tuple(checks),
+        passed=passed,
+        failed=failed,
+        skipped=len(checks) - passed - failed,
+    )
+
+
+def _message_file_check(space: Workspace, path: Path) -> tuple[bool, str]:
+    message = path.parent / "message with spaces.txt"
+    message.write_text(AI, encoding="utf-8")
+    code, _ = _cli(space, path, "check", "--message-file", str(message))
+    return code == 1, f"exit {code}"
+
+
+def _uninstall_probe(space: Workspace, path: Path, repository: Repository) -> tuple[bool, str]:
+    uninstall_hooks(repository)
+    states = {s.hook.value: s.state.value for s in _statuses(repository)}
+    before = space.git(path, "rev-parse", "HEAD").stdout
+    result = space.git(path, "commit", "--quiet", "--allow-empty", "-m", AI, check=False)
+    created = space.git(path, "rev-parse", "HEAD").stdout != before
+    ok = all(state == HookState.MISSING.value for state in states.values()) and created
+    return (
+        ok,
+        f"hooks {states}; AI commit exit {result.returncode}, "
+        f"{'created' if created else 'not created'}",
+    )

commitguard/research/report.py

@@ -0,0 +1,372 @@
+"""Security and benchmark reports assembled from recorded evidence.
+
+Nothing here computes a result: every number is read from a recorded benchmark
+result (``benchmarks/results/raw/``) or from evidence written by the test suites
+(``COMMITGUARD_EVIDENCE_DIR``). Anything that has no evidence is reported as
+``Not tested`` rather than left out, so the report cannot quietly overstate what
+is known.
+
+Every statement carries one label:
+
+``Measured``   a number from a recorded benchmark run on a stated machine;
+``Tested``     an automated test asserts it (test suites, experiments);
+``Observed``   an experiment recorded what actually happened, including failures
+               and documented bypasses;
+``Expected``   design intent that no test covers yet;
+``Not tested`` no evidence.
+"""
+
+import json
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from commitguard import __version__
+from commitguard.research.results import latest, load_results
+
+LABELS = ("Measured", "Tested", "Observed", "Expected", "Not tested")
+BENCHMARKS = ("detection", "performance", "hooks", "repository", "platform")
+
+
+def _read_json(path: Path) -> Any:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+def _read_jsonl(path: Path) -> list[dict[str, Any]]:
+    entries: list[dict[str, Any]] = []
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return entries
+    for line in text.splitlines():
+        if line.strip():
+            try:
+                entries.append(json.loads(line))
+            except ValueError:
+                continue
+    return entries
+
+
+def _environment(manifest: dict[str, Any]) -> str:
+    return (
+        f"{manifest.get('operating_system')} {manifest.get('os_release')} "
+        f"({manifest.get('machine')}), {manifest.get('cpu_model')}, "
+        f"{manifest.get('cpu_count')} CPUs, Python {manifest.get('python_version')}, "
+        f"Git {manifest.get('git_version')}"
+    )
+
+
+def collect(results_dir: Path, evidence_dir: Path | None) -> dict[str, Any]:
+    """Gather every recorded result and piece of evidence into one document."""
+    documents = {name: latest(results_dir, name) for name in BENCHMARKS}
+    history = [
+        {
+            "benchmark": document.get("benchmark"),
+            "file": path.relative_to(results_dir).as_posix(),
+            "timestamp": document.get("manifest", {}).get("timestamp"),
+            "commitguard_version": document.get("manifest", {}).get("commitguard_version"),
+            "dataset_version": document.get("manifest", {}).get("dataset_version"),
+            "source_revision": document.get("manifest", {}).get("source_revision"),
+        }
+        for path, document in load_results(results_dir)
+    ]
+    experiments = _read_jsonl(evidence_dir / "experiments.jsonl") if evidence_dir else []
+    fuzzing = _read_json(evidence_dir / "fuzzing.json") if evidence_dir else None
+    redos = _read_json(evidence_dir / "redos.json") if evidence_dir else None
+    return {
+        "generated_at": datetime.now(UTC).isoformat(),
+        "commitguard_version": __version__,
+        "results_directory": str(results_dir),
+        "evidence_directory": str(evidence_dir) if evidence_dir else None,
+        "latest": {
+            name: (
+                {"file": path.relative_to(results_dir).as_posix(), **document}
+                if (pair := documents[name]) and (path := pair[0]) and (document := pair[1])
+                else None
+            )
+            for name in BENCHMARKS
+        },
+        "history": history,
+        "experiments": experiments,
+        "fuzzing": fuzzing,
+        "redos": redos,
+    }
+
+
+def _detection_section(document: dict[str, Any] | None) -> list[str]:
+    if document is None:
+        return ["| Detection accuracy | Not tested | no recorded detection run |"]
+    result, manifest = document["result"], document["manifest"]
+    decision = result["decision"]
+    rates = result["decision_rates"]
+
+    def percent(key: str) -> str:
+        value = rates.get(key)
+        return "n/a" if value is None else f"{value * 100:.3f}%"
+
+    return [
+        f"| False negatives | Measured | {decision['false_negative']} of {result['positives']} "
+        f"cases that must not be allowed (dataset {manifest.get('dataset_version')}) |",
+        f"| False positives | Measured | {decision['false_positive']} of {result['negatives']} "
+        f"clean cases |",
+        f"| Precision / recall | Measured | {percent('precision')} / {percent('recall')} |",
+        f"| False positive rate / false negative rate | Measured | {percent('false_positive_rate')}"
+        f" / {percent('false_negative_rate')} |",
+        f"| Detection latency per commit | Measured | p50 {result['latency']['p50_ms']:.4f} ms, "
+        f"p95 {result['latency']['p95_ms']:.4f} ms, p99 {result['latency']['p99_ms']:.4f} ms |",
+    ]
+
+
+def _performance_section(document: dict[str, Any] | None) -> list[str]:
+    if document is None:
+        return ["| Performance | Not tested | no recorded performance run |"]
+    result = document["result"]
+    batches = result.get("batches") or []
+    messages = result.get("message_sizes") or []
+    lines = []
+    if batches:
+        biggest = batches[-1]
+        lines.append(
+            f"| Throughput | Measured | {biggest['commits_per_second']:.1f} commits/s on "
+            f"{biggest['commits']} commits "
+            f"(p50 {biggest['latency']['p50_ms']:.4f} ms per commit) |"
+        )
+    if messages:
+        biggest = messages[-1]
+        lines.append(
+            f"| Large commit messages | Measured | {biggest['message_bytes']:,} byte message: "
+            f"p50 {biggest['latency']['p50_ms']:.3f} ms |"
+        )
+    peak = result.get("peak_rss_bytes")
+    if peak:
+        lines.append(f"| Peak memory | Measured | {peak / 1048576:.1f} MiB for the whole run |")
+    return lines or ["| Performance | Not tested | recorded run has no measurements |"]
+
+
+def _hooks_section(document: dict[str, Any] | None) -> list[str]:
+    if document is None:
+        return ["| Hook overhead | Not tested | no recorded hooks run |"]
+    result = document["result"]
+    lines = []
+    for overhead in result.get("overhead", []):
+        lines.append(
+            f"| Hook overhead: {overhead['operation']} | Measured | "
+            f"+{overhead['overhead_p50_ms']:.0f} ms "
+            f"({overhead['without_hooks_p50_ms']:.1f} -> {overhead['with_hooks_p50_ms']:.1f} ms, "
+            f"median of {result.get('repetitions', '?')} runs) |"
+        )
+    for observation in result.get("observations", []):
+        lines.append(
+            f"| {observation['check']} | Observed | {observation['observed']} "
+            f"(expected {observation['expected']}) |"
+        )
+    return lines or ["| Hook overhead | Not tested | recorded run has no measurements |"]
+
+
+def _platform_section(document: dict[str, Any] | None) -> list[str]:
+    if document is None:
+        return ["| Cross-platform validation | Not tested | no recorded platform run |"]
+    result = document["result"]
+    return [
+        f"| Local enforcement on {result['system']} | Tested | {result['passed']} passed, "
+        f"{result['failed']} failed, {result['skipped']} skipped |"
+    ]
+
+
+def _repository_section(document: dict[str, Any] | None) -> list[str]:
+    if document is None:
+        return ["| Repository history scanning | Not tested | no recorded repository run |"]
+    histories = document["result"].get("histories") or []
+    if not histories:
+        return ["| Repository history scanning | Not tested | recorded run has no measurements |"]
+    biggest = histories[-1]
+    return [
+        f"| Repository history scanning | Measured | {biggest['commits']} commits in "
+        f"{biggest['scan_total_ms'] / 1000:.1f} s ({biggest['commits_per_second']:.0f} commits/s); "
+        f"{biggest['blocked']} of {biggest['seeded_violations']} seeded violations found |"
+    ]
+
+
+def _experiment_rows(experiments: Iterable[dict[str, Any]]) -> list[str]:
+    rows = []
+    for entry in sorted(
+        experiments, key=lambda item: (item.get("area", ""), item.get("attack", ""))
+    ):
+        rows.append(
+            f"| {entry.get('area', '')} | {entry.get('attack', '')} | "
+            f"**{entry.get('outcome', '')}** | {entry.get('observed', '')} | "
+            f"{entry.get('mitigation', '')} |"
+        )
+    return rows
+
+
+def render_security_report(data: dict[str, Any]) -> str:
+    latest_results = data["latest"]
+    detection = latest_results.get("detection")
+    lines = [
+        "# CommitGuard security report",
+        "",
+        f"Generated {data['generated_at']} for CommitGuard {data['commitguard_version']}.",
+        "",
+        "Every row is labelled: **Measured** (a number from a recorded benchmark run),",
+        "**Tested** (an automated test asserts it), **Observed** (an experiment recorded what",
+        "happened, including bypasses), **Expected** (design intent, not yet covered by a test)",
+        "or **Not tested**. Nothing in this report is estimated.",
+        "",
+    ]
+    if detection:
+        lines += [
+            "## Environment of the latest runs",
+            "",
+            f"- Detection: {_environment(detection['manifest'])}",
+            f"- Source revision: `{detection['manifest'].get('source_revision')}`"
+            f" (dirty: {detection['manifest'].get('source_dirty')})",
+            "",
+        ]
+    lines += [
+        "## Detection",
+        "",
+        "| Statement | Label | Evidence |",
+        "|---|---|---|",
+        *_detection_section(detection),
+        "",
+        "## Performance",
+        "",
+        "| Statement | Label | Evidence |",
+        "|---|---|---|",
+        *_performance_section(latest_results.get("performance")),
+        *_repository_section(latest_results.get("repository")),
+        *_hooks_section(latest_results.get("hooks")),
+        "",
+        "## Cross-platform validation",
+        "",
+        "| Statement | Label | Evidence |",
+        "|---|---|---|",
+        *_platform_section(latest_results.get("platform")),
+        "",
+    ]
+    experiments = data.get("experiments") or []
+    lines += ["## Security experiments", ""]
+    if experiments:
+        outcomes: dict[str, int] = {}
+        for entry in experiments:
+            outcome = str(entry.get("outcome", "unknown"))
+            outcomes[outcome] = outcomes.get(outcome, 0) + 1
+        lines += [
+            f"{len(experiments)} recorded experiments: "
+            + ", ".join(f"{count} {name}" for name, count in sorted(outcomes.items()))
+            + ".",
+            "",
+            "| Area | Attack | Outcome | Observed | Mitigation |",
+            "|---|---|---|---|---|",
+            *_experiment_rows(experiments),
+            "",
+        ]
+    else:
+        lines += [
+            "Not tested here: no experiment evidence was found. Run",
+            "`commitguard reproduce security --evidence-dir <dir>` first.",
+            "",
+        ]
+    fuzzing, redos = data.get("fuzzing"), data.get("redos")
+    lines += ["## Fuzzing and ReDoS", ""]
+    if fuzzing:
+        lines += [
+            f"- **Tested**: {fuzzing['total_executed']} property-based examples across "
+            f"{len(fuzzing['executed'])} properties "
+            f"({'derandomized' if fuzzing.get('derandomized') else 'randomized'}).",
+        ]
+    else:
+        lines.append("- **Not tested**: no fuzzing evidence found.")
+    if redos:
+        worst = max((item["worst_seconds"] for item in redos["patterns"].values()), default=0.0)
+        lines += [
+            f"- **Measured**: {len(redos['patterns'])} regular expressions run against "
+            f"{redos['adversarial_inputs_per_pattern']} adversarial inputs of "
+            f"{redos['input_characters']} characters; worst case {worst * 1000:.1f} ms "
+            f"(budget {redos['budget_seconds'] * 1000:.0f} ms).",
+        ]
+    else:
+        lines.append("- **Not tested**: no ReDoS evidence found.")
+    lines += [
+        "",
+        "## Recorded runs",
+        "",
+        "Results are immutable: a new run is a new file, and earlier results are kept.",
+        "",
+        "| Benchmark | Runs |",
+        "|---|---|",
+    ]
+    counts: dict[str, int] = {}
+    for entry in data["history"]:
+        name = str(entry.get("benchmark"))
+        counts[name] = counts.get(name, 0) + 1
+    for name in sorted(counts):
+        lines.append(f"| {name} | {counts[name]} |")
+    lines += [
+        "",
+        "## What this report does not say",
+        "",
+        "- It does not claim CommitGuard cannot be bypassed: local hooks are bypassable by the",
+        "  person running them, and the experiments record exactly that.",
+        "- Results labelled Measured come from the machine named above, not from a controlled",
+        "  laboratory, and were not repeated across machines.",
+        "- No external party has reproduced these results yet.",
+        "",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def render_benchmark_report(data: dict[str, Any]) -> str:
+    lines = [
+        "# CommitGuard benchmark report",
+        "",
+        f"Generated {data['generated_at']} for CommitGuard {data['commitguard_version']}.",
+        "",
+        "Every number below is read from a recorded result file; none is recomputed here.",
+        "",
+        "| Benchmark | Latest run | Version | Environment |",
+        "|---|---|---|---|",
+    ]
+    for name in BENCHMARKS:
+        document = data["latest"].get(name)
+        if document is None:
+            lines.append(f"| {name} | not recorded | - | - |")
+            continue
+        manifest = document["manifest"]
+        lines.append(
+            f"| {name} | `{document['file']}` | {manifest.get('commitguard_version')} | "
+            f"{manifest.get('operating_system')} {manifest.get('os_release')}, "
+            f"Python {manifest.get('python_version')} |"
+        )
+    lines += [
+        "",
+        "## All recorded runs",
+        "",
+        "| Benchmark | File | Timestamp | Dataset |",
+        "|---|---|---|---|",
+    ]
+    for entry in data["history"]:
+        lines.append(
+            f"| {entry['benchmark']} | `{entry['file']}` | {entry['timestamp']} | "
+            f"{entry.get('dataset_version') or '-'} |"
+        )
+    return "\n".join(lines) + "\n"
+
+
+def write_reports(data: dict[str, Any], output_dir: Path) -> list[Path]:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    written = []
+    for name, content in (
+        ("security-report.json", json.dumps(data, indent=2, sort_keys=True) + "\n"),
+        ("security-report.md", render_security_report(data)),
+        ("benchmark-report.md", render_benchmark_report(data)),
+    ):
+        target = output_dir / name
+        target.write_text(content, encoding="utf-8")
+        written.append(target)
+    return written