primarysource 0.1.0__py3-none-any.whl

primarysource/kconfig/catalogue.py

@@ -0,0 +1,98 @@
+"""The `kconfig` collection: the kernel's Kconfig and Kbuild documents, read as reStructuredText.
+
+Source, placement and pin (read from the repositories on 2026-11-13, see `docs/kconfig.md`):
+
+- the tree is `Documentation/kbuild/` of torvalds/linux at the commit of the tag `v7.3`, fetched as a gitiles
+  subtree archive from kernel.googlesource.com (57 KB; the whole-repository tarball is two orders larger). The
+  documents are the twelve `.rst` files there: `kconfig-language` (the language), `kconfig-macro-language`,
+  `kconfig` (the configuration targets), `kbuild`, `makefiles`, `modules`, and the rest;
+- the licence is GPL-2.0-only: the kernel's `COPYING` at the root says "GPL-2.0 WITH Linux-syscall-note" and
+  names the syscall note's scope as the user-space API headers, and `Documentation/process/license-rules.rst`
+  gives the kernel as "GPL version 2 only". Three of the twelve files carry an `SPDX-License-Identifier` line;
+  the build records it as the document's `licence` and records the rest as `GPL-2.0-only (COPYING, no file tag)`;
+- placement is **layer**.
+
+pkgtrust R165 and kconfigpy read `kconfig-language` for the grammar of a Kconfig file; refs into it are
+`kconfig:kconfig-language§Menu entries` and, once pinned, `kconfig:kconfig-language@c03c1a14§Menu entries`.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from collections.abc import Mapping
+
+from primarysource.errors import LibError
+from primarysource.pkgdocs.fetch import Source
+from primarysource.pkgdocs.model import Doc
+from primarysource.pkgdocs.readers._common import decode
+from primarysource.pkgdocs.readers.rst import read_rst
+from primarysource.pkgdocs.runtime import Build, Licence, Pin, Spec, TreeSpec, matching
+
+COMMIT = "c03c1a14507dfaf8b856c2608f9ac216021fc222"
+
+PIN = Pin(
+    commit=COMMIT,
+    label="v7.3",
+    date="2026-10-18",
+    files_sha256="36d3fe2bf74fee4efef91f7a16a56297966652812e314f8122eb4e5d0cd13ecd",
+    sources=(
+        Source(
+            f"https://kernel.googlesource.com/pub/scm/linux/kernel/git/torvalds/linux/+archive/{COMMIT}/Documentation/kbuild.tar.gz",
+            strip=0,
+        ),
+    ),
+)
+
+LICENCE = Licence(
+    spdx="GPL-2.0-only",
+    redistribute="layer",
+    attribution="Linux kernel developers; GPL-2.0-only",
+    evidence="COPYING and Documentation/process/license-rules.rst at torvalds/linux " + COMMIT[:12],
+)
+
+_SPDX = re.compile(r"SPDX-License-Identifier:\s*([^\n]+)")
+
+
+def build(files: Mapping[str, bytes], pin: Pin) -> Build:
+    docs: list[Doc] = []
+    skipped: Counter[str] = Counter()
+    for path in sorted(files):
+        stem = path[: -len(".rst")]
+        try:
+            doc = read_rst(files[path], stem)
+            tag = _SPDX.search(decode(files[path], path))
+        except LibError:
+            skipped["not UTF-8 text"] += 1
+            continue
+        licence = tag.group(1).strip() if tag else "GPL-2.0-only (COPYING, no file tag)"
+        docs.append(doc.with_meta(path=f"Documentation/kbuild/{path}", licence=licence))
+    return Build(tuple(docs), {}, skipped)
+
+
+SPEC = Spec(
+    name="kconfig",
+    title="Linux Kconfig and Kbuild documentation",
+    licence=LICENCE,
+    trees=(
+        TreeSpec(
+            name="kbuild",
+            title="Documentation/kbuild/ of torvalds/linux (reStructuredText)",
+            pins=(PIN,),
+            include=matching(r"[a-z][a-z0-9_.-]*\.rst"),
+            build=build,
+        ),
+    ),
+    instructions=(
+        "The kernel's Kconfig language reference (kconfig-language), the macro language (kconfig-macro-language), "
+        "the configuration targets (kconfig) and the Kbuild documents (kbuild, makefiles, modules, ...) from the "
+        "user's imported copy at a pinned release. Loop: kconfig_search('<words>') -> "
+        "kconfig_outline('kconfig-language') -> kconfig_read('<ref>'). A document id is its file name without "
+        ".rst. A section is an id (2.1), an anchor (menu-entries), a heading or a unique part of one."
+    ),
+    example_refs=(
+        "kconfig:kconfig-language§Menu entries",
+        "kconfig:kconfig-language§Menu attributes¶3",
+        "kconfig:kconfig-macro-language§Built-in functions",
+    ),
+)

primarysource/kconfig/cli.py

@@ -0,0 +1,12 @@
+"""`primarysource kconfig import|status|docs|outline|read|search|cite`."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from primarysource.kconfig.catalogue import SPEC
+from primarysource.pkgdocs.serving import run
+
+
+def main(argv: Sequence[str]) -> int:
+    return run(SPEC, argv)

primarysource/kconfig/server.py

@@ -0,0 +1,8 @@
+"""The MCP server for `kconfig` (`primarysource mcp --collection kconfig`). Imports `mcp` when this module loads."""
+
+from __future__ import annotations
+
+from primarysource.kconfig.catalogue import SPEC
+from primarysource.pkgdocs.serving import build_server
+
+server = build_server(SPEC)

primarysource/model.py

@@ -0,0 +1,63 @@
+"""The sectioned-document model the libraries share.
+
+A document is an ordered list of sections; a section is an ordered list of units. What a unit IS differs by
+corpus and cannot be unified honestly: an RFC has real paragraphs (RFCXML `pn` ids), an extracted PDF clause
+only has sentences, a converted HTML article has blocks. So the unit kind is declared, and every result that
+hands out a `¶n` ref says which kind `n` counts.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class Unit(StrEnum):
+    """What `¶n` counts within a section."""
+
+    PARAGRAPH = "paragraph"
+    SENTENCE = "sentence"
+    BLOCK = "block"
+
+
+@dataclass(frozen=True, slots=True)
+class Section:
+    """One addressable part of a document. `units` are in reading order; `¶1` is `units[0]`."""
+
+    id: str
+    title: str
+    units: tuple[str, ...] = ()
+    depth: int = 1
+
+
+@dataclass(frozen=True, slots=True)
+class Document:
+    """A document as the core sees it: an id, a title, the unit kind, and its sections in order."""
+
+    id: str
+    title: str
+    unit: Unit
+    sections: tuple[Section, ...] = field(default=())
+
+    def section(self, section_id: str) -> Section | None:
+        """The first section with this id, or None. Duplicate ids are the segmenter's to report."""
+        for candidate in self.sections:
+            if candidate.id == section_id:
+                return candidate
+        return None
+
+    def duplicate_ids(self) -> tuple[str, ...]:
+        """Section ids that occur more than once, in first-seen order: an ambiguity to warn about."""
+        seen: set[str] = set()
+        repeated: list[str] = []
+        for candidate in self.sections:
+            if candidate.id in seen and candidate.id not in repeated:
+                repeated.append(candidate.id)
+            seen.add(candidate.id)
+        return tuple(repeated)
+
+
+def span_hash(text: str) -> str:
+    """`sha256:<16 hex>` of the exact text cited, so a citation can be checked against a later extraction."""
+    return "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()[:16]

primarysource/nist/__init__.py

@@ -0,0 +1,5 @@
+"""NIST publications: corpus index, search, and citation."""
+
+from primarysource.nist.models import Document, Section
+
+__all__ = ["Document", "Section"]

primarysource/nist/collection.py

@@ -0,0 +1,46 @@
+"""NIST publications (SP 800, FIPS) as a primarysource collection. Importing this needs nothing beyond the core."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from primarysource.model import Unit
+from primarysource.pdfcorpus.tools import GRAMMAR
+from primarysource.registry import Collection
+
+# The server registers the bare names (search, read, outline, info, cite); `primarysource mcp` serves them as
+# nist_search, ... and `--bare-names` keeps nistlib's names. Refs: `<doc_id>§<section>` and `<doc_id>:<first>-<last>`.
+COLLECTION = Collection(
+    name="nist",
+    title="NIST publications (SP 800, SP 1800, FIPS), fetched by the user",
+    prefix="nist_",
+    unit=Unit.BLOCK,
+    grammar=GRAMMAR,
+    server="primarysource.nist.server.mcp:mcp",
+    cli="primarysource.nist.collection:main",
+    identify="primarysource.nist.identify:identify",
+)
+
+
+def main(argv: Sequence[str]) -> int:
+    """`primarysource nist fetch ...` (download, extract, index), `primarysource nist oscal ...`,
+    `primarysource nist index` (rebuild the search index from the fetched corpus) and `primarysource nist status`
+    (write `defaults.json`, so a bare name such as "NIST SP 800-53" resolves to its current final revision)."""
+    commands = {
+        "fetch": "primarysource.nist.ingest.fetch",
+        "oscal": "primarysource.nist.ingest.oscal",
+        "status": "primarysource.nist.ingest.status",
+    }
+    if argv and argv[0] == "index":
+        from primarysource.nist.spec import SPEC
+        from primarysource.pdfcorpus import fts
+
+        return fts.main(SPEC, argv[1:])
+    if not argv or argv[0] not in commands:
+        names = ",".join([*commands, "index"])
+        print(f"usage: primarysource nist {{{names}}} [args]", flush=True)
+        return 2
+    import importlib
+
+    module = importlib.import_module(commands[argv[0]])
+    return int(module.main(list(argv[1:])))