touchneedle 0.1.0__tar.gz

touchneedle-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ncoleman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

touchneedle-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: touchneedle
+Version: 0.1.0
+Summary: Verify that every citation and reference in a document is real, accurately described, and consistently used.
+Author: ncoleman
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nicoleman0/touchneedle
+Project-URL: Source, https://github.com/nicoleman0/touchneedle
+Project-URL: Changelog, https://github.com/nicoleman0/touchneedle/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/nicoleman0/touchneedle/issues
+Keywords: citations,references,bibliography,academic,fact-checking
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# touchneedle
+
+Citiation tool that verifies the citations in a document are real,
+accurately described, and consistently used.
+
+Useful for both students and examiners who wish to corroborate citations.
+
+It works standalone, or as a coding agent skill.
+
+Most commercial citation checkers want a `.bib` file and check it against academic
+databases. That covers journal articles but misses standards,
+specifications, vendor documentation, and blog posts. In a lot of real
+bibliographies, this is half the list.
+
+So this tool parses a **prose reference list** (Harvard/author-date)
+straight out of Markdown or `.docx`, and routes each entry to whichever
+authority can actually confirm it.
+
+## What it checks
+
+**Existence and metadata** — scripted and deterministic:
+
+| Entry carries | Checked against |
+|---|---|
+| arXiv id | arXiv API |
+| DOI | Crossref |
+| RFC number | IETF datatracker, falling back to rfc-editor |
+| `draft-*` name | IETF datatracker, **including whether the cited revision is still current** |
+| Quoted title in an academic venue | Crossref, then OpenAlex, by title |
+| A URL and nothing else | Fetched live; page title compared with the cited title |
+
+Entries with both an identifier and a URL get both, so a real paper behind a dead
+link is still reported. Detects the fabricated-citation signature — a real title
+carrying the wrong authors — as `MISMATCH`.
+
+**Internal consistency** — every in-text citation resolves to a list entry, every
+list entry is cited somewhere, and `2025a`/`2025b` suffixes are used unambiguously.
+
+**Claim support** — the pass that needs reading rather than fetching. `claims`
+emits a worklist pairing each in-text citation with the sentence making the claim
+and a locator for the source; the model then reads each source and rules
+SUPPORTED / PARTIAL / UNSUPPORTED / INACCESSIBLE. This catches the failure the
+database checks cannot: a genuine source attached to a claim it does not make.
+
+## Install
+
+As a command-line tool:
+
+```bash
+pip install touchneedle
+```
+
+As a Claude Code skill:
+
+```bash
+git clone https://github.com/nicoleman0/touchneedle ~/.claude/skills/touchneedle
+```
+
+Or as a Claude Code plugin:
+
+```
+/plugin marketplace add nicoleman0/touchneedle
+/plugin install touchneedle
+```
+
+There are no dependencies beyond Python 3.11+. `pandoc` is needed only for `.docx` input.
+
+Then, in Claude Code: *"check the citations in thesis.docx"*.
+
+## Use directly
+
+```bash
+touchneedle check thesis.docx --out report.md --json data.json
+touchneedle claims thesis.docx --out claims.md
+```
+
+From a clone, without installing, that is `python3 scripts/touchneedle.py …` —
+the same file either way.
+
+Options: `--offline` (parse and cross-check only, no network), `--cache DIR`
+(HTTP cache, 7-day TTL, so re-runs are nearly free), `--timeout N`, and
+`--mailto you@example.com` for Crossref and OpenAlex's polite rate-limit pool.
+`--mailto` is off by default and never inferred — it sends an address to third
+parties.
+
+`check` exits 2 when something needs attention, 0 when clean, so it drops into CI.
+
+## Statuses
+
+`MISMATCH` and `NOT_FOUND` are the ones that damage a submission. `LINK_DEAD` and
+`STALE` need a fix but not a retraction. `PARTIAL`, `LINK_MOVED` and
+`UNVERIFIABLE` are for a glance — notably, PDFs and JS-rendered pages land in
+`PARTIAL` routinely, because no `<title>` can be read from them. A `PARTIAL` is a
+limit of the check, not evidence against the citation.
+
+## Limits
+
+Author-date reference lists only — numeric styles (Vancouver, IEEE) are not
+parsed. Page numbers, edition and publisher details are not checked.
+
+Sources behind paywalls cannot be verified beyond their metadata record.
+
+The list of in-text citations with no matching entry has expected false positives,
+because a regex cannot distinguish `(Smith, 2024)` from `(ICLR 2023)`.
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -t tests
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
+
+The short version: standard library only, tests stay offline, and never let a coverage gap
+report itself as a finding.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).

touchneedle-0.1.0/README.md

@@ -0,0 +1,119 @@
+# touchneedle
+
+Citiation tool that verifies the citations in a document are real,
+accurately described, and consistently used.
+
+Useful for both students and examiners who wish to corroborate citations.
+
+It works standalone, or as a coding agent skill.
+
+Most commercial citation checkers want a `.bib` file and check it against academic
+databases. That covers journal articles but misses standards,
+specifications, vendor documentation, and blog posts. In a lot of real
+bibliographies, this is half the list.
+
+So this tool parses a **prose reference list** (Harvard/author-date)
+straight out of Markdown or `.docx`, and routes each entry to whichever
+authority can actually confirm it.
+
+## What it checks
+
+**Existence and metadata** — scripted and deterministic:
+
+| Entry carries | Checked against |
+|---|---|
+| arXiv id | arXiv API |
+| DOI | Crossref |
+| RFC number | IETF datatracker, falling back to rfc-editor |
+| `draft-*` name | IETF datatracker, **including whether the cited revision is still current** |
+| Quoted title in an academic venue | Crossref, then OpenAlex, by title |
+| A URL and nothing else | Fetched live; page title compared with the cited title |
+
+Entries with both an identifier and a URL get both, so a real paper behind a dead
+link is still reported. Detects the fabricated-citation signature — a real title
+carrying the wrong authors — as `MISMATCH`.
+
+**Internal consistency** — every in-text citation resolves to a list entry, every
+list entry is cited somewhere, and `2025a`/`2025b` suffixes are used unambiguously.
+
+**Claim support** — the pass that needs reading rather than fetching. `claims`
+emits a worklist pairing each in-text citation with the sentence making the claim
+and a locator for the source; the model then reads each source and rules
+SUPPORTED / PARTIAL / UNSUPPORTED / INACCESSIBLE. This catches the failure the
+database checks cannot: a genuine source attached to a claim it does not make.
+
+## Install
+
+As a command-line tool:
+
+```bash
+pip install touchneedle
+```
+
+As a Claude Code skill:
+
+```bash
+git clone https://github.com/nicoleman0/touchneedle ~/.claude/skills/touchneedle
+```
+
+Or as a Claude Code plugin:
+
+```
+/plugin marketplace add nicoleman0/touchneedle
+/plugin install touchneedle
+```
+
+There are no dependencies beyond Python 3.11+. `pandoc` is needed only for `.docx` input.
+
+Then, in Claude Code: *"check the citations in thesis.docx"*.
+
+## Use directly
+
+```bash
+touchneedle check thesis.docx --out report.md --json data.json
+touchneedle claims thesis.docx --out claims.md
+```
+
+From a clone, without installing, that is `python3 scripts/touchneedle.py …` —
+the same file either way.
+
+Options: `--offline` (parse and cross-check only, no network), `--cache DIR`
+(HTTP cache, 7-day TTL, so re-runs are nearly free), `--timeout N`, and
+`--mailto you@example.com` for Crossref and OpenAlex's polite rate-limit pool.
+`--mailto` is off by default and never inferred — it sends an address to third
+parties.
+
+`check` exits 2 when something needs attention, 0 when clean, so it drops into CI.
+
+## Statuses
+
+`MISMATCH` and `NOT_FOUND` are the ones that damage a submission. `LINK_DEAD` and
+`STALE` need a fix but not a retraction. `PARTIAL`, `LINK_MOVED` and
+`UNVERIFIABLE` are for a glance — notably, PDFs and JS-rendered pages land in
+`PARTIAL` routinely, because no `<title>` can be read from them. A `PARTIAL` is a
+limit of the check, not evidence against the citation.
+
+## Limits
+
+Author-date reference lists only — numeric styles (Vancouver, IEEE) are not
+parsed. Page numbers, edition and publisher details are not checked.
+
+Sources behind paywalls cannot be verified beyond their metadata record.
+
+The list of in-text citations with no matching entry has expected false positives,
+because a regex cannot distinguish `(Smith, 2024)` from `(ICLR 2023)`.
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -t tests
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
+
+The short version: standard library only, tests stay offline, and never let a coverage gap
+report itself as a finding.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).

touchneedle-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "touchneedle"
+# Single source of truth: __version__ in scripts/touchneedle.py. setuptools
+# parses it statically, without importing the module. See RELEASING.md.
+dynamic = ["version"]
+description = "Verify that every citation and reference in a document is real, accurately described, and consistently used."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "ncoleman" }]
+keywords = ["citations", "references", "bibliography", "academic", "fact-checking"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Text Processing :: Markup",
+    "Topic :: Scientific/Engineering",
+]
+# Deliberately empty, and it should stay that way. The other install path is a
+# bare `git clone` into a skills directory, where nothing gets pip-installed.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/nicoleman0/touchneedle"
+Source = "https://github.com/nicoleman0/touchneedle"
+Changelog = "https://github.com/nicoleman0/touchneedle/blob/main/CHANGELOG.md"
+Issues = "https://github.com/nicoleman0/touchneedle/issues"
+
+[project.scripts]
+touchneedle = "touchneedle:main"
+
+# One module, kept at scripts/touchneedle.py so that the path SKILL.md invokes
+# is the same file pip installs. The two distribution paths never diverge.
+[tool.setuptools]
+py-modules = ["touchneedle"]
+
+[tool.setuptools.dynamic]
+version = { attr = "touchneedle.__version__" }
+
+[tool.setuptools.package-dir]
+"" = "scripts"
+
+# Dev-only, and deliberately a dependency group rather than an optional extra:
+# a group can never be pulled in by `pip install touchneedle[...]`, so the
+# zero-runtime-dependency promise above cannot be weakened by accident.
+# Pinned with ~= because an unpinned linter adds rules on its own schedule and
+# reddens CI on an unrelated pull request.
+[dependency-groups]
+dev = ["ruff~=0.16.5", "mypy~=2.3"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+# plugins/ holds a generated copy of scripts/touchneedle.py -- linting it
+# would report every finding twice. sync-plugin-skill.sh regenerates it.
+extend-exclude = ["plugins/"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4", "SIM"]
+
+# `ruff format` is deliberately not run over this repo. build_report() and
+# build_claims() assemble Markdown from hand-aligned list literals, which the
+# formatter reflows into a diff nobody can review for no readability gain.
+[tool.mypy]
+python_version = "3.11"
+strict = true

touchneedle-0.1.0/scripts/touchneedle.egg-info/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: touchneedle
+Version: 0.1.0
+Summary: Verify that every citation and reference in a document is real, accurately described, and consistently used.
+Author: ncoleman
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nicoleman0/touchneedle
+Project-URL: Source, https://github.com/nicoleman0/touchneedle
+Project-URL: Changelog, https://github.com/nicoleman0/touchneedle/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/nicoleman0/touchneedle/issues
+Keywords: citations,references,bibliography,academic,fact-checking
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# touchneedle
+
+Citiation tool that verifies the citations in a document are real,
+accurately described, and consistently used.
+
+Useful for both students and examiners who wish to corroborate citations.
+
+It works standalone, or as a coding agent skill.
+
+Most commercial citation checkers want a `.bib` file and check it against academic
+databases. That covers journal articles but misses standards,
+specifications, vendor documentation, and blog posts. In a lot of real
+bibliographies, this is half the list.
+
+So this tool parses a **prose reference list** (Harvard/author-date)
+straight out of Markdown or `.docx`, and routes each entry to whichever
+authority can actually confirm it.
+
+## What it checks
+
+**Existence and metadata** — scripted and deterministic:
+
+| Entry carries | Checked against |
+|---|---|
+| arXiv id | arXiv API |
+| DOI | Crossref |
+| RFC number | IETF datatracker, falling back to rfc-editor |
+| `draft-*` name | IETF datatracker, **including whether the cited revision is still current** |
+| Quoted title in an academic venue | Crossref, then OpenAlex, by title |
+| A URL and nothing else | Fetched live; page title compared with the cited title |
+
+Entries with both an identifier and a URL get both, so a real paper behind a dead
+link is still reported. Detects the fabricated-citation signature — a real title
+carrying the wrong authors — as `MISMATCH`.
+
+**Internal consistency** — every in-text citation resolves to a list entry, every
+list entry is cited somewhere, and `2025a`/`2025b` suffixes are used unambiguously.
+
+**Claim support** — the pass that needs reading rather than fetching. `claims`
+emits a worklist pairing each in-text citation with the sentence making the claim
+and a locator for the source; the model then reads each source and rules
+SUPPORTED / PARTIAL / UNSUPPORTED / INACCESSIBLE. This catches the failure the
+database checks cannot: a genuine source attached to a claim it does not make.
+
+## Install
+
+As a command-line tool:
+
+```bash
+pip install touchneedle
+```
+
+As a Claude Code skill:
+
+```bash
+git clone https://github.com/nicoleman0/touchneedle ~/.claude/skills/touchneedle
+```
+
+Or as a Claude Code plugin:
+
+```
+/plugin marketplace add nicoleman0/touchneedle
+/plugin install touchneedle
+```
+
+There are no dependencies beyond Python 3.11+. `pandoc` is needed only for `.docx` input.
+
+Then, in Claude Code: *"check the citations in thesis.docx"*.
+
+## Use directly
+
+```bash
+touchneedle check thesis.docx --out report.md --json data.json
+touchneedle claims thesis.docx --out claims.md
+```
+
+From a clone, without installing, that is `python3 scripts/touchneedle.py …` —
+the same file either way.
+
+Options: `--offline` (parse and cross-check only, no network), `--cache DIR`
+(HTTP cache, 7-day TTL, so re-runs are nearly free), `--timeout N`, and
+`--mailto you@example.com` for Crossref and OpenAlex's polite rate-limit pool.
+`--mailto` is off by default and never inferred — it sends an address to third
+parties.
+
+`check` exits 2 when something needs attention, 0 when clean, so it drops into CI.
+
+## Statuses
+
+`MISMATCH` and `NOT_FOUND` are the ones that damage a submission. `LINK_DEAD` and
+`STALE` need a fix but not a retraction. `PARTIAL`, `LINK_MOVED` and
+`UNVERIFIABLE` are for a glance — notably, PDFs and JS-rendered pages land in
+`PARTIAL` routinely, because no `<title>` can be read from them. A `PARTIAL` is a
+limit of the check, not evidence against the citation.
+
+## Limits
+
+Author-date reference lists only — numeric styles (Vancouver, IEEE) are not
+parsed. Page numbers, edition and publisher details are not checked.
+
+Sources behind paywalls cannot be verified beyond their metadata record.
+
+The list of in-text citations with no matching entry has expected false positives,
+because a regex cannot distinguish `(Smith, 2024)` from `(ICLR 2023)`.
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -t tests
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
+
+The short version: standard library only, tests stay offline, and never let a coverage gap
+report itself as a finding.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).

touchneedle-0.1.0/scripts/touchneedle.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+scripts/touchneedle.py
+scripts/touchneedle.egg-info/PKG-INFO
+scripts/touchneedle.egg-info/SOURCES.txt
+scripts/touchneedle.egg-info/dependency_links.txt
+scripts/touchneedle.egg-info/entry_points.txt
+scripts/touchneedle.egg-info/top_level.txt
+tests/test_citations.py
+tests/test_cli.py
+tests/test_parsing.py
+tests/test_verify.py

touchneedle-0.1.0/scripts/touchneedle.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

touchneedle-0.1.0/scripts/touchneedle.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+touchneedle = touchneedle:main

touchneedle-0.1.0/scripts/touchneedle.egg-info/top_level.txt

@@ -0,0 +1 @@
+touchneedle