stackvox 0.11.0__tar.gz → 0.12.0__tar.gz

{stackvox-0.11.0/stackvox.egg-info → stackvox-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.11.0
+Version: 0.12.0
 Summary: Offline TTS library using Kokoro-82M
 Author-email: "StackOne Technologies Ltd." <support@stackone.com>
 License-Expression: Apache-2.0

{stackvox-0.11.0 → stackvox-0.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stackvox"
-version = "0.11.0"
+version = "0.12.0"
 description = "Offline TTS library using Kokoro-82M"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -61,6 +61,14 @@ stackvox = ["py.typed", "data/stackvox-say"]
 line-length = 110
 target-version = "py310"
 
+[tool.ruff.format]
+# Ruff 0.16 began formatting Python code blocks inside Markdown. Ours are
+# illustrative rather than real code, and their layout is deliberate: the
+# `normalize_for_speech` signature in docs/speech-normalization.md aligns its
+# trailing comments into a readable column of flags, which the formatter
+# collapses. Prose is a human call, so keep the formatter to the code.
+exclude = ["*.md"]
+
 [tool.ruff.lint]
 select = [
     "E",   # pycodestyle errors

{stackvox-0.11.0 → stackvox-0.12.0}/stackvox/cli.py

@@ -87,7 +87,7 @@ _stackvox_completion() {
             ;;
     esac
 
-    local norm_flags="--no-markdown --no-dev-terms --pronunciations --no-expand-units --no-expand-numbers --no-pauses --tables --code-blocks --code-placeholder --strip-emoji --no-terminal-stops --locale"
+    local norm_flags="--no-markdown --no-dev-terms --no-filenames --pronunciations --no-expand-units --no-expand-numbers --no-pauses --tables --code-blocks --code-placeholder --strip-emoji --no-terminal-stops --locale"
 
     case "$subcommand" in
         speak)
@@ -220,6 +220,12 @@ def _add_normalize_args(parser: argparse.ArgumentParser, *, with_switch: bool) -
         action="store_false",
         help="Do not spell out dev acronyms espeak mispronounces (CLI, CI, IDE, AWS, URI, IAM, ...)",
     )
+    parser.add_argument(
+        "--no-filenames",
+        dest="filenames",
+        action="store_false",
+        help="Leave filenames and paths as written (no 'README dot md', no 'line 42 of cli dot py')",
+    )
     parser.add_argument(
         "--no-expand-units",
         dest="expand_units",
@@ -294,6 +300,7 @@ def _normalize_kwargs(args: argparse.Namespace) -> dict:
         "markdown": args.markdown,
         "pronunciations": _load_pronunciations(args.pronunciations),
         "dev_terms": args.dev_terms,
+        "filenames": args.filenames,
         "expand_units": args.expand_units,
         "expand_numbers": args.expand_numbers,
         "pauses": args.pauses,
@@ -425,12 +432,21 @@ def _cmd_status(_: argparse.Namespace) -> int:
         rc = 0
         # The running daemon can lag the installed package if it wasn't restarted
         # after an upgrade — surface that skew instead of trusting it blindly.
+        # Only a daemon that is genuinely BEHIND wants restarting; a newer one
+        # means the client just run is the older install (a checkout alongside a
+        # global one), and restarting would downgrade what's serving.
         got, running_version = daemon.version()
         if got and running_version != installed:
-            print(
-                f"daemon running {running_version}, but {installed} is installed "
-                f"— restart the daemon (stackvox stop; stackvox serve) to pick it up"
-            )
+            if updates._is_newer(installed, running_version):
+                print(
+                    f"daemon running {running_version}, but {installed} is installed "
+                    f"— restart the daemon (stackvox stop; stackvox serve) to pick it up"
+                )
+            else:
+                print(
+                    f"daemon running {running_version} is newer than the {installed} client "
+                    f"you just ran; no restart needed"
+                )
     else:
         print("stopped")
         rc = 1

{stackvox-0.11.0 → stackvox-0.12.0}/stackvox/daemon.py

@@ -26,6 +26,7 @@ import socket
 import socketserver
 import sys
 import threading
+import time
 from typing import Any
 
 import sounddevice as sd
@@ -42,6 +43,10 @@ MAX_QUEUE = 2
 WORKER_POLL_SECONDS = 0.5
 CLIENT_TIMEOUT_SECONDS = 1.0
 PING_TIMEOUT_SECONDS = 0.5
+# How long `stop` waits for the daemon process to actually exit after it has
+# acknowledged the request, and how often it re-checks.
+STOP_TIMEOUT_SECONDS = 5.0
+STOP_POLL_SECONDS = 0.05
 RECV_BYTES = 1024
 
 
@@ -273,14 +278,19 @@ def _pid_alive(pid: int) -> bool:
         return False
 
 
-def is_running() -> bool:
+def _read_pid() -> int | None:
+    """The pid recorded in the pid file, or None if absent or unparseable."""
     if not PID_PATH.exists():
-        return False
+        return None
     try:
-        pid = int(PID_PATH.read_text().strip())
-    except ValueError:
-        return False
-    return _pid_alive(pid)
+        return int(PID_PATH.read_text().strip())
+    except (ValueError, OSError):
+        return None
+
+
+def is_running() -> bool:
+    pid = _read_pid()
+    return pid is not None and _pid_alive(pid)
 
 
 def _check_for_update_async() -> None:
@@ -359,8 +369,29 @@ def say(
     return send(req)
 
 
-def stop() -> tuple[bool, str]:
-    return send({"command": "stop"})
+def stop(timeout: float = STOP_TIMEOUT_SECONDS) -> tuple[bool, str]:
+    """Shut the daemon down and wait until the process has actually gone.
+
+    The daemon acknowledges the request and only then unwinds `serve_forever`
+    and removes its pid file, so returning on the ack alone made
+    `stackvox stop && stackvox serve` race: `serve` still saw a live pid, refused
+    to start, and the shutdown then completed, leaving nothing running at all.
+    Reporting success before the process has exited makes that sequence, the one
+    `status` recommends, silently useless.
+    """
+    pid = _read_pid()
+    ok, resp = send({"command": "stop"})
+    if not ok or pid is None:
+        # Nothing acknowledged, or no pid to watch: the caller's own
+        # `is_running` check is as good as it gets.
+        return ok, resp
+    deadline = time.monotonic() + timeout
+    while True:
+        if not _pid_alive(pid):
+            return True, resp
+        if time.monotonic() >= deadline:
+            return False, f"daemon acknowledged stop but pid {pid} is still alive after {timeout:g}s"
+        time.sleep(STOP_POLL_SECONDS)
 
 
 def cancel() -> tuple[bool, str]:

{stackvox-0.11.0 → stackvox-0.12.0}/stackvox/text.py

@@ -12,6 +12,7 @@ exposed for composition and testing. See ``docs/speech-normalization.md``.
 from __future__ import annotations
 
 import re
+from collections.abc import Callable
 
 __all__ = [
     "normalize_for_speech",
@@ -19,8 +20,10 @@ __all__ = [
     "strip_emoji",
     "strip_thousands_separators",
     "versions_to_words",
+    "speak_versions",
     "decimals_to_words",
     "speak_file_refs",
+    "speak_file_names",
     "expand_units",
     "apply_pronunciations",
     "shape_pauses",
@@ -102,6 +105,81 @@ def versions_to_words(text: str) -> str:
     return _VERSION.sub(lambda m: m.group(0).replace(".", " point "), text)
 
 
+# --------------------------------------------------------------------------- #
+# Semantic versions                                                           #
+# --------------------------------------------------------------------------- #
+# `versions_to_words` handles the dotted digits. This handles everything else
+# in a semver string, all of which espeak gets wrong:
+#
+#   * a pre-release suffix GLUES to the core: "1.2.3-rc.1" voices as
+#     "one point two point three-arsee-one" (hyphen swallowed, suffix dot silent)
+#   * "^", ">" and "<" are SILENT, so "^1.2.3" is indistinguishable from a pin
+#   * ">=" is broken by our own `=` rule below, which splits it into "> equals",
+#     and a bare ">" voices as nothing, so ">=1.2.3" says "equals 1.2.3",
+#     inverting the meaning. espeak reads an intact ">=" correctly, so this stage
+#     must consume the operator BEFORE `expand_units` sees the "=".
+#   * "1.x" voices as "one ex" (dot silent)
+#
+# "~" is left to `expand_units`, which already maps it to "about"; accidentally
+# the right reading for a tilde range.
+
+# Longest operators first: ">=" must win before ">". Each requires a following
+# digit (optionally "v"-prefixed), which keeps the rules in version context and
+# off ordinary punctuation. The leading `(\S?)` captures whatever non-space
+# character precedes the operator and re-emits it with a space, so glued forms
+# like pip's "requests>=2.0" or "arr[i]<5" don't fuse into "requestsat least".
+_VERSION_OPERATORS: list[tuple[str, str]] = [
+    (r"(\S?)>=\s*(?=v?\d)", "at least "),
+    (r"(\S?)<=\s*(?=v?\d)", "at most "),
+    (r"(\S?)==\s*(?=v?\d)", "exactly "),
+    (r"(\S?)!=\s*(?=v?\d)", "not equal to "),
+    (r"(\S?)>\s*(?=v?\d)", "above "),
+    (r"(\S?)<\s*(?=v?\d)", "below "),
+]
+
+# "^" only at a token start: "x^2" and ")^2" are exponentiation, not a range.
+_CARET_RANGE = re.compile(r"(?<![\w)])\^\s*(?=v?\d)")
+
+# A dotted core (>=2 parts, so a bare "100" can't match) followed by a
+# "-prerelease" or "+build" suffix.
+_VERSION_SUFFIX = re.compile(r"(?<![\w.])(v?\d+(?:\.\d+){1,3})([-+][0-9A-Za-z][0-9A-Za-z.-]*)(?![\w])")
+
+# Wildcard versions: "1.x", "2.*", "1.2.X".
+_VERSION_WILDCARD = re.compile(r"(?<![\w.])(v?\d+(?:\.\d+)*)\.([xX*])(?![\w])")
+
+
+def _operator_repl(spoken: str) -> Callable[[re.Match[str]], str]:
+    """Replacement that re-emits the captured boundary character with a space."""
+
+    def repl(match: re.Match[str]) -> str:
+        boundary = match.group(1)
+        return f"{boundary} {spoken}" if boundary else spoken
+
+    return repl
+
+
+def speak_versions(text: str) -> str:
+    """Voice the non-numeric parts of a semantic version.
+
+    ``1.2.3-rc.1`` -> "1.2.3, rc 1"; ``>=1.2.3`` -> "at least 1.2.3";
+    ``^1.2.3`` -> "compatible with 1.2.3"; ``1.x`` -> "1 dot x". The dotted
+    digits are left for :func:`versions_to_words`, which runs later, so this
+    stage only unglues and names things espeak drops.
+
+    Must run BEFORE :func:`expand_units`, whose ``=`` rule would otherwise split
+    ``>=`` into a silent ``>`` plus "equals".
+    """
+    for pattern, words in _VERSION_OPERATORS:
+        text = re.sub(pattern, _operator_repl(words), text)
+    text = _CARET_RANGE.sub("compatible with ", text)
+    # Suffix: comma for a beat, then the tag's own dots and hyphens as spaces.
+    text = _VERSION_SUFFIX.sub(
+        lambda m: f"{m.group(1)}, {re.sub(r'[.-]', ' ', m.group(2)[1:])}",
+        text,
+    )
+    return _VERSION_WILDCARD.sub(r"\1 dot \2", text)
+
+
 def decimals_to_words(text: str) -> str:
     """1198.9 -> "1198 point 9"; 770.72 -> "770 point 7 2". Removes the bare
     "." between digits, which TTS can otherwise read as a full stop."""
@@ -113,45 +191,257 @@ def decimals_to_words(text: str) -> str:
 
 
 # --------------------------------------------------------------------------- #
-# File & line references                                                      #
+# File & path references                                                      #
 # --------------------------------------------------------------------------- #
-# `engine.py:42` reads as "…dot py colon forty two" — the dots and colon get
-# voiced literally. Spoken aloud the line number is the signal and the filename
-# is noise, so lead with "line N of <file>" (how a person actually says it) and
-# soften the path: drop directories to the basename, and voice the dotted name
-# word by word.
+# espeak already spells extensions correctly on its own: ".md" voices as "em
+# dee", ".tf" as "tee eff", ".json" as "jason", so these stages deliberately
+# leave the extension alone. What espeak gets wrong is everything around it:
+#
+#   * the dot between stem and extension is SILENT ("README.md" -> "readmee-emdee")
+#   * a hyphen inside a name is swallowed ("speech-normalization" -> one word)
+#   * a leading dot is silent, so ".github" reads as "github"
+#   * "~/" glues into "tilde-slash"
+#   * ".yml" reads as "immle" (".yaml" is fine)
+#
+# So: voice the dot, space the hyphens, voice a leading dot, say "home" for "~",
+# and alias the one bad extension. Directory segments are spoken with "slash"
+# between them, which is how a person reads a path aloud.
+
+# Only these extensions mark a dotted token as a filename. An allowlist, not a
+# general "word.word" rule, because ordinary prose is full of lookalikes espeak
+# ALREADY voices correctly and which must not be touched: attribute access
+# (os.path.join, self.assertEqual), abbreviations (e.g., i.e., U.S.), and
+# domains (example.com, claude.ai) all fall outside it for free.
+# Single-letter extensions (.c, .h, .r) are deliberately absent: they would
+# rewrite initials like "J.R.R" into "J dot R dot R". Those files keep espeak's
+# existing reading rather than risk a prose regression.
+_FILE_EXTENSIONS = frozenset(
+    [
+        "py",
+        "pyi",
+        "pyx",
+        "ipynb",
+        "rb",
+        "rs",
+        "go",
+        "java",
+        "kt",
+        "kts",
+        "swift",
+        "cpp",
+        "hpp",
+        "cc",
+        "cxx",
+        "cs",
+        "php",
+        "lua",
+        "pl",
+        "scala",
+        "clj",
+        "cljs",
+        "ex",
+        "exs",
+        "erl",
+        "vim",
+        "el",
+        "ts",
+        "tsx",
+        "js",
+        "jsx",
+        "mjs",
+        "cjs",
+        "vue",
+        "svelte",
+        "astro",
+        "json",
+        "yaml",
+        "yml",
+        "toml",
+        "ini",
+        "cfg",
+        "conf",
+        "env",
+        "xml",
+        "csv",
+        "tsv",
+        "properties",
+        "lock",
+        "md",
+        "mdx",
+        "rst",
+        "txt",
+        "adoc",
+        "tex",
+        "html",
+        "htm",
+        "css",
+        "scss",
+        "sass",
+        "less",
+        "svg",
+        "tf",
+        "tfvars",
+        "tfstate",
+        "mk",
+        "cmake",
+        "gradle",
+        "bzl",
+        "proto",
+        "graphql",
+        "gql",
+        "sql",
+        "sh",
+        "bash",
+        "zsh",
+        "fish",
+        "ps1",
+        "bat",
+        "dockerfile",
+        "gitignore",
+        "editorconfig",
+        "npmrc",
+        "nvmrc",
+        "log",
+        "wav",
+        "mp3",
+        "pdf",
+        "png",
+        "jpg",
+        "jpeg",
+        "gif",
+        "webp",
+        "zip",
+        "tar",
+        "gz",
+        "whl",
+    ]
+)
+
+# Extensions espeak mispronounces, mapped to a spelling it reads correctly.
+# ".yml" -> "immle"; the "yaml" spelling voices as "yaml".
+_EXTENSION_ALIASES: dict[str, str] = {"yml": "yaml"}
+
+# Dotted tokens that LOOK like "name.ext" with a real extension but are read as
+# a single product name. Compared lowercased against the whole matched token.
+_NOT_FILENAMES = frozenset({"node.js", "next.js", "nuxt.js", "vue.js", "ember.js", "backbone.js"})
+
+
+def _speak_segment(segment: str) -> str:
+    """Space out a hyphenated path segment: "speech-normalization" -> "speech
+    normalization". espeak swallows the hyphen and runs the halves together.
+    Underscores are left alone; espeak doesn't voice them."""
+    return segment.replace("-", " ")
+
+
+def _speak_basename(name: str) -> str:
+    """``speech-normalization.md`` -> "speech normalization dot md".
+
+    Every dot becomes a spoken "dot" (espeak drops it), hyphens become spaces,
+    and the final extension is run through the alias map. The extension itself
+    is otherwise untouched; espeak spells it correctly already.
+    """
+    segments = name.split(".")
+    segments[-1] = _EXTENSION_ALIASES.get(segments[-1].lower(), segments[-1])
+    return " dot ".join(_speak_segment(segment) for segment in segments)
+
+
+def _speak_dirs(path: str) -> str:
+    """``src/lib/`` -> "src slash lib"; ``~/.config/`` -> "home slash dot config".
+
+    A leading dot and a ``~`` are both mis-voiced by espeak (silent, and
+    "tilde-slash" respectively), so they're spelled out here.
+    """
+    spoken: list[str] = []
+    for segment in path.split("/"):
+        if not segment or segment == ".":
+            continue
+        if segment == "~":
+            spoken.append("home")
+        elif segment == "..":
+            spoken.append("dot dot")
+        elif segment.startswith("."):
+            spoken.append("dot " + _speak_segment(segment[1:]))
+        else:
+            spoken.append(_speak_segment(segment))
+    return " slash ".join(spoken)
+
+
+def _is_filename(basename: str) -> bool:
+    """True when the final dotted component is a known file extension."""
+    if basename.lower() in _NOT_FILENAMES:
+        return False
+    return basename.rsplit(".", 1)[-1].lower() in _FILE_EXTENSIONS
+
+
+# Directory segments, captured. The inner segment allows empty, so an absolute
+# "/abs/path/" is consumed by the match rather than left stranded in the text.
+_DIRS = r"((?:[\w.~-]*/)*)"
+_BASENAME = r"([A-Za-z0-9_-]+(?:\.[A-Za-z][\w-]*)+)"  # name with >=1 letter-initial extension
 
 _FILE_REF = re.compile(
     r"(?<!\w)"
-    r"(?:[\w.-]*/)*"  # optional directory segments (dropped — "src/" reads as "slash")
-    r"([A-Za-z0-9_-]+(?:\.[A-Za-z][\w-]*)+)"  # filename with >=1 letter-initial extension
-    r":(\d+)(?:-(\d+))?(?::(\d+))?"  # :line, optional -end (range) or :column
-    r"(?!\w)"
+    + _DIRS
+    + _BASENAME
+    + r":(\d+)(?:-(\d+))?(?::(\d+))?"  # :line, optional -end (range) or :column
+    + r"(?!\w)"
 )
 
+# Same shape without the ":line" suffix. The trailing guard allows a following
+# "." so a sentence-final "See README.md." still matches.
+_FILE_NAME = re.compile(r"(?<![\w/~.-])" + _DIRS + _BASENAME + r"(?![\w-])")
+
 
 def speak_file_refs(text: str) -> str:
-    """Turn ``path/file.ext:line`` refs into spoken "line N of file ext".
+    """Turn ``path/file.ext:line`` refs into spoken "line N of file dot ext in path".
 
-    ``engine.py:42`` -> "line 42 of engine py"; ``cli.py:100-118`` -> "lines 100
-    to 118 of cli py"; ``foo.ts:666:10`` -> "line 666, column 10 of foo ts". The
-    ``:line`` suffix is the trigger, so bare times/ratios/verses (``12:30``,
-    ``3:1``, ``John 3:16``) and dotted versions (``1.2.3``) are left untouched —
+    ``engine.py:42`` -> "line 42 of engine dot py"; ``src/cli.py:100-118`` ->
+    "lines 100 to 118 of cli dot py in src"; ``foo.ts:666:10`` -> "line 666,
+    column 10 of foo dot ts". The line number leads because spoken aloud it's
+    the signal, and the directory trails as a prepositional phrase, which is how
+    a person says it.
+
+    The ``:line`` suffix is the trigger, so bare times/ratios/verses (``12:30``,
+    ``3:1``, ``John 3:16``) and dotted versions (``1.2.3``) are left untouched --
     none of them carry a dotted-filename before the colon.
     """
 
     def repl(match: re.Match[str]) -> str:
-        basename = match.group(1).replace(".", " ")
-        start, end, column = match.group(2), match.group(3), match.group(4)
+        dirs, basename = match.group(1), match.group(2)
+        start, end, column = match.group(3), match.group(4), match.group(5)
         if end:
             location = f"lines {start} to {end}"
         else:
             location = f"line {start}" + (f", column {column}" if column else "")
-        return f"{location} of {basename}"
+        spoken = f"{location} of {_speak_basename(basename)}"
+        directories = _speak_dirs(dirs)
+        return f"{spoken} in {directories}" if directories else spoken
 
     return _FILE_REF.sub(repl, text)
 
 
+def speak_file_names(text: str) -> str:
+    """Voice a bare filename or path, with no ``:line`` suffix needed.
+
+    ``README.md`` -> "README dot md"; ``docs/speech-normalization.md`` -> "docs
+    slash speech normalization dot md". Gated on a known extension
+    (:data:`_FILE_EXTENSIONS`), so prose lookalikes espeak already reads
+    correctly (``os.path.join``, ``e.g.``, ``example.com``) pass through.
+
+    Run this AFTER :func:`speak_file_refs`: that stage rewrites its own matches
+    into prose containing no dotted token, so the two never fight over one ref.
+    """
+
+    def repl(match: re.Match[str]) -> str:
+        dirs, basename = match.group(1), match.group(2)
+        if not _is_filename(basename):
+            return match.group(0)
+        spoken = _speak_basename(basename)
+        directories = _speak_dirs(dirs)
+        return f"{directories} slash {spoken}" if directories else spoken
+
+    return _FILE_NAME.sub(repl, text)
+
+
 # --------------------------------------------------------------------------- #
 # Pronunciations                                                              #
 # --------------------------------------------------------------------------- #
@@ -360,18 +650,24 @@ def _shape_paragraph(
     text: str,
     *,
     pronunciations: dict[str, str] | None,
-    dev_terms_flag: bool,
+    filenames_flag: bool,
     expand_units_flag: bool,
     expand_numbers_flag: bool,
     pauses_flag: bool,
     locale: str,
 ) -> str:
-    # File refs first: it consumes the ":line" digits (so the number stages see a
-    # plain "line 42", not a decimal) and forms the spoken basename before the
-    # dev-term dict runs over it.
-    if dev_terms_flag:
+    # Filenames first, for two reasons: the ref stage consumes the ":line" digits
+    # (so the number stages see a plain "line 42", not a decimal), and spacing the
+    # dot leaves the stem a standalone word, which is what lets the dev-term dict
+    # below still fix "cli" -> "C L I" without gluing it to the extension.
+    # Refs before bare names: the ref stage rewrites its matches into prose with
+    # no dotted token left, so the two never fight over the same reference.
+    if filenames_flag:
         text = speak_file_refs(text)
+        text = speak_file_names(text)
     if expand_numbers_flag:
+        # Version ranges before units: the "=" unit rule would split ">=".
+        text = speak_versions(text)
         text = strip_thousands_separators(text)
     if pauses_flag:
         text = shape_pauses(text)
@@ -391,6 +687,7 @@ def normalize_for_speech(
     markdown: bool = True,
     pronunciations: dict[str, str] | None = None,
     dev_terms: bool = True,
+    filenames: bool = True,
     expand_units: bool = True,
     expand_numbers: bool = True,
     pauses: bool = True,
@@ -429,7 +726,7 @@ def normalize_for_speech(
         shaped = _shape_paragraph(
             para,
             pronunciations=effective_pronunciations,
-            dev_terms_flag=dev_terms,
+            filenames_flag=filenames,
             expand_units_flag=expand_units_flag,
             expand_numbers_flag=expand_numbers_flag,
             pauses_flag=pauses,

{stackvox-0.11.0 → stackvox-0.12.0}/stackvox/updates.py

@@ -18,6 +18,7 @@ from __future__ import annotations
 import json
 import logging
 import os
+import sys
 import urllib.error
 import urllib.request
 from dataclasses import dataclass
@@ -26,14 +27,51 @@ from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _pkg_version
 from pathlib import Path
 
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - covered by 3.10 CI
+    import tomli as tomllib
+
 from stackvox.paths import cache_dir
 
 logger = logging.getLogger(__name__)
 
 
+def _source_tree_version(pyproject: Path | None = None) -> str | None:
+    """Our version from `pyproject.toml`, when running from a source checkout.
+
+    An editable install records its version in dist metadata at install time, so
+    the moment a release bumps `pyproject.toml` that metadata goes stale. The
+    developer then gets a phantom "update available: 0.9.0 -> 0.11.0" against
+    their own tree, and `status` reads the running daemon as newer than the
+    "installed" package and tells them to restart it for no reason.
+
+    Returns None when there's no such file (a normal pip/pipx install) or when it
+    isn't ours, so the metadata path stays authoritative for real installs.
+    """
+    path = pyproject or Path(__file__).resolve().parent.parent / "pyproject.toml"
+    try:
+        with path.open("rb") as handle:
+            data = tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError):
+        return None
+    project = data.get("project")
+    if not isinstance(project, dict) or project.get("name") != "stackvox":
+        return None
+    version = project.get("version")
+    return version if isinstance(version, str) else None
+
+
 def _current_version() -> str:
     """Read our own installed version. Late-bound so importing this module
-    early in the package init chain doesn't trip a circular import."""
+    early in the package init chain doesn't trip a circular import.
+
+    A source checkout wins over dist metadata, which goes stale on an editable
+    install after every release.
+    """
+    from_source = _source_tree_version()
+    if from_source is not None:
+        return from_source
     try:
         return _pkg_version("stackvox")
     except PackageNotFoundError:

{stackvox-0.11.0 → stackvox-0.12.0/stackvox.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.11.0
+Version: 0.12.0
 Summary: Offline TTS library using Kokoro-82M
 Author-email: "StackOne Technologies Ltd." <support@stackone.com>
 License-Expression: Apache-2.0

{stackvox-0.11.0 → stackvox-0.12.0}/tests/test_cli.py

@@ -129,6 +129,7 @@ def _norm_ns(text=None, file=None, **overrides):
         markdown=True,
         pronunciations=None,
         dev_terms=True,
+        filenames=True,
         expand_units=True,
         expand_numbers=True,
         pauses=True,
@@ -291,6 +292,27 @@ class TestCmdStatus:
         assert "0.5.0" in out and "0.8.0" in out  # the skew is surfaced
         assert "restart" in out.lower()
 
+    def test_running_does_not_advise_restart_when_the_daemon_is_ahead(self, mocker, capsys):
+        """A daemon NEWER than the client means the client is the older install,
+        so restarting would downgrade what's serving."""
+        mocker.patch.object(cli.daemon, "is_running", return_value=True)
+        pid_path = mocker.MagicMock()
+        pid_path.read_text.return_value = "1\n"
+        mocker.patch.object(cli.daemon, "PID_PATH", pid_path)
+        mocker.patch.object(cli.daemon, "SOCKET_PATH", "/tmp/x.sock")
+        mocker.patch.object(cli.daemon, "version", return_value=(True, "0.11.0"))
+        mocker.patch.object(cli.updates, "_current_version", return_value="0.9.0")
+        mocker.patch.object(cli.updates, "check_for_update", return_value=None)
+
+        rc = cli._cmd_status(_ns())
+
+        assert rc == 0
+        out = capsys.readouterr().out
+        assert "0.11.0" in out and "0.9.0" in out
+        assert "stackvox stop" not in out  # the restart advice itself
+        assert "newer" in out.lower()
+        assert "no restart needed" in out
+
     def test_stopped_returns_one(self, mocker, capsys):
         mocker.patch.object(cli.daemon, "is_running", return_value=False)
         rc = cli._cmd_status(_ns())

{stackvox-0.11.0 → stackvox-0.12.0}/tests/test_daemon.py

@@ -78,6 +78,9 @@ class TestSendHelpers:
         assert send.call_args.args[0] == {"text": "hi"}
 
     def test_stop_sends_command_stop(self, mocker):
+        # _read_pid is mocked out so the wait-for-exit loop can't reach a real
+        # daemon's pid file and block on a live process.
+        mocker.patch.object(daemon, "_read_pid", return_value=None)
         send = mocker.patch.object(daemon, "send", return_value=(True, "ok"))
         daemon.stop()
         assert send.call_args.args[0] == {"command": "stop"}
@@ -136,3 +139,72 @@ class TestStartDeviceWatcher:
         with caplog.at_level(logging.DEBUG, logger="stackvox.daemon"):
             daemon._start_device_watcher()  # must not raise
         assert any("CoreAudio unavailable" in r.message for r in caplog.records)
+
+
+class TestStopWaitsForExit:
+    """`stop` reports success only once the process has actually gone.
+
+    The daemon acknowledges the request before unwinding, so returning on the
+    ack made `stackvox stop && stackvox serve` race: serve saw a live pid and
+    refused, then the shutdown finished, leaving nothing running.
+    """
+
+    def test_returns_send_failure_unchanged(self, mocker):
+        mocker.patch.object(daemon, "_read_pid", return_value=4242)
+        mocker.patch.object(daemon, "send", return_value=(False, "daemon not running"))
+
+        actual = daemon.stop()
+
+        assert actual == (False, "daemon not running")
+
+    def test_does_not_wait_when_no_pid_is_recorded(self, mocker):
+        mocker.patch.object(daemon, "_read_pid", return_value=None)
+        mocker.patch.object(daemon, "send", return_value=(True, "ok"))
+        alive = mocker.patch.object(daemon, "_pid_alive")
+
+        actual = daemon.stop()
+
+        assert actual == (True, "ok")
+        alive.assert_not_called()
+
+    def test_waits_until_the_process_has_exited(self, mocker):
+        mocker.patch.object(daemon, "_read_pid", return_value=4242)
+        mocker.patch.object(daemon, "send", return_value=(True, "ok"))
+        alive = mocker.patch.object(daemon, "_pid_alive", side_effect=[True, True, False])
+        sleep = mocker.patch.object(daemon.time, "sleep")
+
+        actual = daemon.stop()
+
+        assert actual == (True, "ok")
+        assert alive.call_count == 3
+        assert sleep.call_count == 2
+
+    def test_fails_when_the_process_outlives_the_timeout(self, mocker):
+        mocker.patch.object(daemon, "_read_pid", return_value=4242)
+        mocker.patch.object(daemon, "send", return_value=(True, "ok"))
+        mocker.patch.object(daemon, "_pid_alive", return_value=True)
+        mocker.patch.object(daemon.time, "sleep")
+
+        ok, resp = daemon.stop(timeout=0.0)
+
+        assert ok is False
+        assert "still alive" in resp
+        assert "4242" in resp
+
+
+class TestReadPid:
+    def test_returns_none_when_missing(self, mocker, tmp_path):
+        mocker.patch.object(daemon, "PID_PATH", tmp_path / "missing.pid")
+        assert daemon._read_pid() is None
+
+    def test_returns_none_when_unparseable(self, mocker, tmp_path):
+        pid = tmp_path / "garbage.pid"
+        pid.write_text("not-a-number")
+        mocker.patch.object(daemon, "PID_PATH", pid)
+        assert daemon._read_pid() is None
+
+    def test_returns_the_recorded_pid(self, mocker, tmp_path):
+        pid = tmp_path / "live.pid"
+        pid.write_text("4242\n")
+        mocker.patch.object(daemon, "PID_PATH", pid)
+        assert daemon._read_pid() == 4242

{stackvox-0.11.0 → stackvox-0.12.0}/tests/test_text.py

@@ -8,7 +8,9 @@ from stackvox.text import (
     markdown_to_paragraphs,
     normalize_for_speech,
     shape_pauses,
+    speak_file_names,
     speak_file_refs,
+    speak_versions,
     strip_emoji,
     strip_thousands_separators,
     versions_to_words,
@@ -55,23 +57,94 @@ def test_semver_normalizes_end_to_end():
     assert "0 point 7.0" not in out
 
 
-# --- file & line references ------------------------------------------------
+# --- semantic versions -----------------------------------------------------
+
+
+def test_version_prerelease_is_ungluded_from_the_core():
+    """ "1.2.3-rc.1" glues into "three-arsee-one": espeak swallows the hyphen and
+    drops the suffix dot."""
+    assert speak_versions("1.2.3-rc.1") == "1.2.3, rc 1"
+    assert speak_versions("1.2.3-beta.2") == "1.2.3, beta 2"
+
+
+def test_version_build_metadata():
+    assert speak_versions("1.2.3+build.5") == "1.2.3, build 5"
+
+
+def test_version_operators_are_spoken_semantically():
+    assert speak_versions("^1.2.3") == "compatible with 1.2.3"
+    assert speak_versions(">=1.2.3") == "at least 1.2.3"
+    assert speak_versions("<=2.0.0") == "at most 2.0.0"
+    assert speak_versions(">1.0.0") == "above 1.0.0"
+    assert speak_versions("<2.0.0") == "below 2.0.0"
+    assert speak_versions("==1.2.3") == "exactly 1.2.3"
+    assert speak_versions("!=1.2.3") == "not equal to 1.2.3"
+
+
+def test_version_operator_keeps_a_glued_boundary_separate():
+    """pip writes the operator glued to the package name."""
+    assert speak_versions("requests>=2.0") == "requests at least 2.0"
+    assert speak_versions("arr[i]<5") == "arr[i] below 5"
+
+
+def test_caret_exponent_is_not_a_version_range():
+    """ "x^2" is exponentiation; only a token-initial caret is a caret range."""
+    assert speak_versions("x^2 plus 1") == "x^2 plus 1"
+    assert speak_versions("(a+b)^2") == "(a+b)^2"
+
+
+def test_version_wildcard_dot_is_spoken():
+    assert speak_versions("1.x") == "1 dot x"
+    assert speak_versions("2.*") == "2 dot *"
+
+
+def test_version_operator_survives_the_units_equals_rule():
+    """Regression: `expand_units` maps "=" to " equals ", which used to split
+    ">=" into a silent ">" plus "equals", inverting the meaning."""
+    assert normalize_for_speech(">=1.2.3", markdown=False) == "at least 1 point 2 point 3."
+
+
+def test_version_normalizes_end_to_end():
+    actual = normalize_for_speech("Upgrade to ^1.2.3-rc.1 today.", markdown=False)
+    assert actual == "Upgrade to compatible with 1 point 2 point 3, rc 1 today."
+
+
+def test_version_leaves_line_ranges_and_dates_alone():
+    assert speak_versions("cli.py:100-118") == "cli.py:100-118"
+    assert speak_versions("released 2026-09-08") == "released 2026-09-08"
+
+
+def test_version_leaves_two_part_numbers_to_the_decimal_stage():
+    """A two-part version is indistinguishable from a decimal, where
+    digit-by-digit is the correct reading. Deliberately untouched."""
+    assert normalize_for_speech("770.72", markdown=False) == "770 point 7 2."
+    assert normalize_for_speech("3.11", markdown=False) == "3 point 1 1."
+
+
+# --- file & path references ------------------------------------------------
 
 
 def test_file_ref_leads_with_line_then_file():
-    assert speak_file_refs("unifiedAPIv2.service.ts:666") == "line 666 of unifiedAPIv2 service ts"
+    """Every dot is spoken, including one inside a multi-part name."""
+    assert speak_file_refs("unifiedAPIv2.service.ts:666") == "line 666 of unifiedAPIv2 dot service dot ts"
+
+
+def test_file_ref_trails_directories_after_the_file():
+    assert speak_file_refs("Open /abs/path/to/module.py:7.") == (
+        "Open line 7 of module dot py in abs slash path slash to."
+    )
 
 
-def test_file_ref_drops_directories_to_basename():
-    assert speak_file_refs("Open /abs/path/to/module.py:7.") == "Open line 7 of module py."
+def test_file_ref_without_directories_has_no_trailing_clause():
+    assert speak_file_refs("engine.py:42") == "line 42 of engine dot py"
 
 
 def test_file_ref_line_range():
-    assert speak_file_refs("cli.py:100-118") == "lines 100 to 118 of cli py"
+    assert speak_file_refs("src/cli.py:100-118") == "lines 100 to 118 of cli dot py in src"
 
 
 def test_file_ref_line_and_column():
-    assert speak_file_refs("foo.ts:666:10") == "line 666, column 10 of foo ts"
+    assert speak_file_refs("foo.ts:666:10") == "line 666, column 10 of foo dot ts"
 
 
 def test_file_ref_leaves_times_ratios_verses_untouched():
@@ -85,12 +158,86 @@ def test_file_ref_leaves_dotted_versions_untouched():
 
 def test_file_ref_normalizes_end_to_end():
     out = normalize_for_speech("See `engine.py:42` for the fix.", markdown=True)
-    assert out == "See line 42 of engine py for the fix."
+    assert out == "See line 42 of engine dot py for the fix."
+
+
+def test_file_name_speaks_the_dot():
+    assert speak_file_names("See README.md for setup.") == "See README dot md for setup."
+
+
+def test_file_name_at_end_of_sentence():
+    assert speak_file_names("Check pyproject.toml.") == "Check pyproject dot toml."
+
+
+def test_file_name_speaks_path_segments_with_slash():
+    actual = speak_file_names("docs/speech-normalization.md")
+    assert actual == "docs slash speech normalization dot md"
+
+
+def test_file_name_spaces_hyphens_espeak_swallows():
+    assert speak_file_names("read-aloud.py") == "read aloud dot py"
+
+
+def test_file_name_voices_leading_dot_and_home():
+    assert speak_file_names(".github/workflows/deploy.yaml") == (
+        "dot github slash workflows slash deploy dot yaml"
+    )
+    assert speak_file_names("~/.config/stackvox/config.toml") == (
+        "home slash dot config slash stackvox slash config dot toml"
+    )
+
+
+def test_file_name_aliases_yml_espeak_reads_as_immle():
+    assert speak_file_names("ci.yml") == "ci dot yaml"
+
+
+def test_file_name_multi_dot_name():
+    assert speak_file_names("vite.config.ts") == "vite dot config dot ts"
+
+
+def test_file_name_requires_a_known_extension():
+    """Attribute access, abbreviations and domains espeak already reads
+    correctly must survive the bare-filename matcher untouched."""
+    for text in [
+        "os.path.join",
+        "self.assertEqual",
+        "Use e.g. this one",
+        "i.e. that one",
+        "U.S. policy",
+        "example.com",
+        "claude.ai",
+        "J.R.R Tolkien",
+    ]:
+        assert speak_file_names(text) == text
+
+
+def test_file_name_leaves_dotted_js_product_names_untouched():
+    assert speak_file_names("Node.js and Next.js") == "Node.js and Next.js"
+
+
+def test_file_name_leaves_refs_to_the_ref_stage():
+    """speak_file_refs runs first and leaves no dotted token behind, so the
+    bare-name stage must not re-touch its output."""
+    once = speak_file_refs("src/cli.py:42")
+    assert speak_file_names(once) == once
+
+
+def test_spacing_the_dot_lets_the_dev_dict_fix_the_stem():
+    """ "cli.py" glued reads as "kligh dot py"; with the dot spaced, the stem is a
+    standalone word the dev-term dict can correct."""
+    assert normalize_for_speech("Look at cli.py.", markdown=False) == "Look at C L I dot py."
+
+
+def test_filenames_disabled():
+    out = normalize_for_speech("See engine.py:42 and README.md.", markdown=False, filenames=False)
+    assert out == "See engine.py:42 and README.md."
 
 
-def test_file_ref_disabled_with_dev_terms():
+def test_filenames_independent_of_dev_terms():
+    """Filenames have their own flag: turning the acronym dict off must not
+    silently disable them."""
     out = normalize_for_speech("See engine.py:42.", markdown=False, dev_terms=False)
-    assert out == "See engine.py:42."
+    assert out == "See line 42 of engine dot py."
 
 
 # --- units -----------------------------------------------------------------

{stackvox-0.11.0 → stackvox-0.12.0}/tests/test_updates.py

@@ -218,3 +218,48 @@ class TestFormatNotice:
         assert "0.3.1" in msg
         assert "0.4.0" in msg
         assert "pipx upgrade stackvox" in msg
+
+
+class TestSourceTreeVersion:
+    """An editable install's dist metadata goes stale the moment a release bumps
+    pyproject, so a source checkout has to win over it."""
+
+    def test_reads_the_version_from_our_own_pyproject(self, tmp_path):
+        path = tmp_path / "pyproject.toml"
+        path.write_text('[project]\nname = "stackvox"\nversion = "1.2.3"\n')
+        assert updates._source_tree_version(path) == "1.2.3"
+
+    def test_ignores_a_pyproject_that_is_not_ours(self, tmp_path):
+        path = tmp_path / "pyproject.toml"
+        path.write_text('[project]\nname = "something-else"\nversion = "1.2.3"\n')
+        assert updates._source_tree_version(path) is None
+
+    def test_returns_none_when_there_is_no_pyproject(self, tmp_path):
+        assert updates._source_tree_version(tmp_path / "nope.toml") is None
+
+    def test_returns_none_when_the_file_is_malformed(self, tmp_path):
+        path = tmp_path / "pyproject.toml"
+        path.write_text("not valid toml {{{")
+        assert updates._source_tree_version(path) is None
+
+    def test_returns_none_when_the_version_is_absent(self, tmp_path):
+        path = tmp_path / "pyproject.toml"
+        path.write_text('[project]\nname = "stackvox"\n')
+        assert updates._source_tree_version(path) is None
+
+
+class TestCurrentVersion:
+    def test_source_tree_beats_stale_dist_metadata(self, mocker):
+        mocker.patch.object(updates, "_source_tree_version", return_value="0.11.0")
+        mocker.patch.object(updates, "_pkg_version", return_value="0.9.0")
+        assert updates._current_version() == "0.11.0"
+
+    def test_falls_back_to_dist_metadata_for_a_real_install(self, mocker):
+        mocker.patch.object(updates, "_source_tree_version", return_value=None)
+        mocker.patch.object(updates, "_pkg_version", return_value="0.11.0")
+        assert updates._current_version() == "0.11.0"
+
+    def test_reports_unknown_when_not_installed_at_all(self, mocker):
+        mocker.patch.object(updates, "_source_tree_version", return_value=None)
+        mocker.patch.object(updates, "_pkg_version", side_effect=updates.PackageNotFoundError)
+        assert updates._current_version() == "0.0.0+unknown"