coding-language-library 0.3.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. coding_language_library-0.3.1/.gitattributes +1 -0
  2. coding_language_library-0.3.1/.github/workflows/refresh-sources.yml +59 -0
  3. coding_language_library-0.3.1/.github/workflows/release.yml +61 -0
  4. coding_language_library-0.3.1/.gitignore +15 -0
  5. coding_language_library-0.3.1/AGENTS.md +32 -0
  6. coding_language_library-0.3.1/ARCHITECTURE.md +22 -0
  7. coding_language_library-0.3.1/DATA-LICENSE.md +22 -0
  8. coding_language_library-0.3.1/LICENSE +25 -0
  9. coding_language_library-0.3.1/PKG-INFO +14 -0
  10. coding_language_library-0.3.1/README.md +103 -0
  11. coding_language_library-0.3.1/SECURITY.md +15 -0
  12. coding_language_library-0.3.1/SOURCES.md +33 -0
  13. coding_language_library-0.3.1/THIRD_PARTY_NOTICES.md +17 -0
  14. coding_language_library-0.3.1/architecture/coding-language-library.architecture.html +14807 -0
  15. coding_language_library-0.3.1/architecture/coding-language-library.architecture.json +190 -0
  16. coding_language_library-0.3.1/architecture/coding-language-library.architecture.png +0 -0
  17. coding_language_library-0.3.1/data/adapters.json +21 -0
  18. coding_language_library-0.3.1/data/discovery_candidates.json +6102 -0
  19. coding_language_library-0.3.1/data/inventory.json +167554 -0
  20. coding_language_library-0.3.1/data/source_state.json +53 -0
  21. coding_language_library-0.3.1/data/sources.json +59 -0
  22. coding_language_library-0.3.1/data/suitability_profiles.json +114 -0
  23. coding_language_library-0.3.1/data/task_profile.schema.json +38 -0
  24. coding_language_library-0.3.1/data/unresolved_matches.json +2341 -0
  25. coding_language_library-0.3.1/data/wikipedia.json +4029 -0
  26. coding_language_library-0.3.1/licenses/Apache-2.0.txt +174 -0
  27. coding_language_library-0.3.1/licenses/GitHub-Linguist-MIT.txt +22 -0
  28. coding_language_library-0.3.1/licenses/Homebrew-BSD-2-Clause.txt +25 -0
  29. coding_language_library-0.3.1/licenses/JetBrainsMono-OFL-1.1.txt +93 -0
  30. coding_language_library-0.3.1/licenses/archify-v3.1.0-MIT.txt +202 -0
  31. coding_language_library-0.3.1/licenses/archify-v3.1.0-THIRD-PARTY-NOTICES.md +78 -0
  32. coding_language_library-0.3.1/mcp/server.py +219 -0
  33. coding_language_library-0.3.1/mcp/task_matching.py +375 -0
  34. coding_language_library-0.3.1/pyproject.toml +22 -0
  35. coding_language_library-0.3.1/scripts/build_inventory.py +448 -0
  36. coding_language_library-0.3.1/scripts/harvest_wikipedia.py +103 -0
  37. coding_language_library-0.3.1/scripts/monitor_sources.py +114 -0
  38. coding_language_library-0.3.1/scripts/verify_inventory.py +179 -0
  39. coding_language_library-0.3.1/tests/test_source_union.py +47 -0
  40. coding_language_library-0.3.1/tests/test_task_matching.py +192 -0
  41. coding_language_library-0.3.1/tests/test_task_matching_evaluation.py +101 -0
  42. coding_language_library-0.3.1/tests/test_wikidata_missing.py +21 -0
  43. coding_language_library-0.3.1/uv.lock +73 -0
@@ -0,0 +1 @@
1
+ architecture/*.html -diff
@@ -0,0 +1,59 @@
1
+ name: Refresh source snapshots
2
+
3
+ on:
4
+ schedule:
5
+ - cron: '17 15 * * 1'
6
+ workflow_dispatch:
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ concurrency:
12
+ group: source-refresh
13
+ cancel-in-progress: false
14
+
15
+ jobs:
16
+ check-and-propose:
17
+ permissions:
18
+ contents: write
19
+ pull-requests: write
20
+ runs-on: ubuntu-latest
21
+ timeout-minutes: 120
22
+ steps:
23
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
24
+ with:
25
+ ref: main
26
+ - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
27
+ with:
28
+ python-version: '3.11'
29
+ - name: Install locked catalogue dependency
30
+ run: python -m pip install --disable-pip-version-check 'PyYAML==6.0.3'
31
+ - name: Check upstream revisions
32
+ id: monitor
33
+ run: python scripts/monitor_sources.py --github-output "$GITHUB_OUTPUT"
34
+ - name: Rebuild and verify changed snapshots
35
+ if: steps.monitor.outputs.changed == 'true'
36
+ run: |
37
+ python scripts/harvest_wikipedia.py
38
+ python scripts/build_inventory.py
39
+ python scripts/verify_inventory.py
40
+ python -m unittest discover -s tests -v
41
+ - name: Open or update review pull request
42
+ if: steps.monitor.outputs.changed == 'true'
43
+ env:
44
+ GH_TOKEN: ${{ github.token }}
45
+ run: |
46
+ git switch -C automated/source-refresh
47
+ git config user.name 'github-actions[bot]'
48
+ git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
49
+ git add data
50
+ if git diff --cached --quiet; then exit 0; fi
51
+ git diff --cached --check
52
+ git commit -m 'Refresh upstream language snapshots'
53
+ git fetch origin automated/source-refresh:refs/remotes/origin/automated/source-refresh || true
54
+ git push --force-with-lease origin automated/source-refresh
55
+ if ! gh pr view automated/source-refresh --json number >/dev/null 2>&1; then
56
+ gh pr create --base main --head automated/source-refresh \
57
+ --title 'Refresh upstream language snapshots' \
58
+ --body 'Review source revisions, catalogue changes, unresolved joins, and source terms before merging.'
59
+ fi
@@ -0,0 +1,61 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - 'v*'
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ release:
13
+ permissions:
14
+ contents: write
15
+ runs-on: ubuntu-latest
16
+ timeout-minutes: 30
17
+ steps:
18
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
19
+ with:
20
+ ref: ${{ github.ref }}
21
+ - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2
22
+ - name: Check the tag matches the package version
23
+ run: |
24
+ project=$(sed -n 's/^version = "\(.*\)"$/\1/p' pyproject.toml)
25
+ server=$(sed -n 's/.*"serverInfo": {"name": "coding-language-library", "version": "\([^"]*\)"}.*/\1/p' mcp/server.py)
26
+ if [ "v$project" != "$GITHUB_REF_NAME" ] || [ "$server" != "$project" ]; then
27
+ echo "tag $GITHUB_REF_NAME, pyproject $project, server $server"
28
+ exit 1
29
+ fi
30
+ - name: Verify inventory and tests
31
+ run: |
32
+ uv run --locked --group catalog python scripts/verify_inventory.py
33
+ uv run --locked --group catalog python -m unittest discover -s tests
34
+ - name: Build the distribution
35
+ run: uv build --out-dir dist
36
+ - name: Smoke-test the wheel without a checkout
37
+ working-directory: ${{ runner.temp }}
38
+ run: |
39
+ wheel=$(ls "$GITHUB_WORKSPACE"/dist/*.whl)
40
+ out=$(uvx --no-cache --from "$wheel" coding-language-library <<'EOF'
41
+ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"release-check","version":"0"}}}
42
+ {"jsonrpc":"2.0","id":2,"method":"tools/list"}
43
+ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_language","arguments":{"name":"Python"}}}
44
+ EOF
45
+ )
46
+ echo "$out" | python3 -c '
47
+ import json, sys
48
+ replies = [json.loads(line) for line in sys.stdin if line.strip()]
49
+ tools = {tool["name"] for tool in replies[1]["result"]["tools"]}
50
+ assert len(tools) == 7, tools
51
+ assert replies[2]["result"]["isError"] is False, replies[2]
52
+ print(sorted(tools))
53
+ '
54
+ - name: Publish to PyPI
55
+ env:
56
+ UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
57
+ run: uv publish dist/*
58
+ - name: Publish the GitHub release
59
+ env:
60
+ GH_TOKEN: ${{ github.token }}
61
+ run: gh release create "$GITHUB_REF_NAME" dist/*.whl dist/*.tar.gz --verify-tag --generate-notes
@@ -0,0 +1,15 @@
1
+ # macOS
2
+ .DS_Store
3
+
4
+ # Local environments and runtime
5
+ .venv/
6
+ __pycache__/
7
+ *.py[cod]
8
+ *.log
9
+
10
+ # Local secrets
11
+ .env
12
+ .env.*
13
+ !.env.example
14
+
15
+ architecture/*.delivery.json
@@ -0,0 +1,32 @@
1
+ # AGENTS.md
2
+
3
+ ## Records
4
+
5
+ - `data/wikipedia.json` is a supplemental discovery snapshot. Refresh it with `scripts/harvest_wikipedia.py`; do not curate its entries by hand.
6
+ - `data/inventory.json` is the canonical source union. It is not defined by the Wikipedia list; rebuild it with `scripts/build_inventory.py` after source changes.
7
+ - Run only one harvest/build sequence at a time; these commands share generated files.
8
+ - `data/sources.json` records source roles, terms, filters, and monitoring methods. `data/source_state.json` records generated revisions, validators, content digests, and counts. Check upstream changes with `scripts/monitor_sources.py` before refreshing.
9
+ - `data/discovery_candidates.json` preserves Wikipedia candidates that link to, conflict with, or are not represented in the canonical union.
10
+ - `data/adapters.json` is the registry for adapter commands and tested pairings. Record a pairing as tested only after a real handshake and tool request succeed.
11
+ - Join source records only through stable identifiers, published crosswalks, exact page links, exact names, or source-published aliases. Leave ambiguous joins unresolved.
12
+ - Keep source provenance, revision or retrieval time, license, match rule, and counts with the generated records.
13
+ - Keep installation identifiers separate from live availability checks. A listed identifier, tool, runtime, or compiler is not proof that it installs, is current, or is present on a machine.
14
+ - Do not promote source descriptions into compatibility claims. Preserve each source's own terms.
15
+
16
+ ## MCP
17
+
18
+ - `mcp/server.py` reads the generated JSON under `data/` and remains read-only.
19
+ - `recommend_stack` and `compare_candidates` never parse the `task` text. Constraint terms left in it are echoed in `unstructured_terms` on every result, so the caller moves them into structured fields.
20
+ - Keep output bounded and paginated. Reject unknown names and invalid filters as tool errors.
21
+ - Do not install packages or launch language servers from the catalogue server.
22
+ - Label a route as tested only when the exact adapter and language-server pair is recorded in `data/adapters.json`.
23
+ - `check_tools` checks `PATH` only; it does not prove that an isolated package manager or coding client is configured.
24
+
25
+ ## Architecture and verification
26
+
27
+ - Review `ARCHITECTURE.md` whenever sources, records, scripts, server behavior, data flow, or runtime boundaries change. Update its editable diagram source and generated views in the same change.
28
+ - Before staging, run the inventory verifier, the unit-test suite, and an official Python MCP SDK client that calls all the listed tools. Keep client scripts and downloaded probes outside the repo.
29
+ - The inventory builder uses the `catalog` dependency group; the MCP server stays standard-library-only.
30
+ - Keep probes and downloaded working files outside the repo. Keep tests focused on source joins, monitoring behavior, and the refresh workflow.
31
+ - Check links, attribution, secrets, staged whitespace, branch, commits, and remotes before handoff.
32
+ - Keep personal names and home-directory paths out of tracked files. Do not use em-dashes in authored prose.
@@ -0,0 +1,22 @@
1
+ # Architecture
2
+
3
+ [Interactive diagram](architecture/coding-language-library.architecture.html) · [Editable diagram source](architecture/coding-language-library.architecture.json)
4
+
5
+ ![Coding language catalogue architecture](architecture/coding-language-library.architecture.png)
6
+
7
+ `harvest_wikipedia.py` records the MediaWiki list as a discovery seed only.
8
+ `build_inventory.py` joins PLDB and Wikidata identity records with GitHub Linguist,
9
+ Mason, and Homebrew metadata; Wikipedia entries do not determine inventory membership.
10
+ `verify_inventory.py` checks the generated snapshot and the curated suitability
11
+ profiles, including claim statuses, conditions, and HTTPS evidence. The stdio
12
+ MCP server reads the committed files. It does not install tools or launch
13
+ language servers. The server runs from a checkout or from the installed
14
+ package, whose wheel bundles the `data/` snapshots alongside `mcp/`;
15
+ the server resolves the first layout that has an inventory.
16
+ `recommend_stack` filters and ranks recorded stacks against
17
+ a structured task profile; conditional support stays unknown, and unevidenced
18
+ constraints are reported rather than guessed. Constraint terms left in the
19
+ task text are flagged in `unstructured_terms`, not parsed.
20
+
21
+ A catalogue match is not a compatibility check. Python with Pyright is the only
22
+ adapter pairing marked tested.
@@ -0,0 +1,22 @@
1
+ # Data terms
2
+
3
+ `LICENSE` covers the project code and authored documentation. It does not grant
4
+ rights to generated catalogue data or third-party material.
5
+
6
+ `data/inventory.json` is an attributed union of source records. Each record names
7
+ its upstream sources and the exact join methods used. No new blanket license is
8
+ applied to those source-derived fields. Follow the terms named in `data/sources.json`
9
+ and the notices below when reusing them.
10
+
11
+ | Data | Source and terms |
12
+ | --- | --- |
13
+ | `data/wikipedia.json`, `data/discovery_candidates.json` | The list text is generally available under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) and [GFDL](https://www.gnu.org/licenses/fdl-1.3.en.html), except where a page history or notice states otherwise. The harvest is a discovery seed, not the authority for inventory membership. The committed snapshot records the page revision. Attribute the page and revision when reusing its material. |
14
+ | Wikidata fields in `data/inventory.json` | Wikidata data is released under CC0 1.0. |
15
+ | PLDB fields in `data/inventory.json` | PLDB states in its upstream README that its data is dedicated to the public domain. Attribution is included here although the README says it is not required. |
16
+ | GitHub Linguist fields in `data/inventory.json` | MIT. The upstream license is retained in `licenses/GitHub-Linguist-MIT.txt`. |
17
+ | Mason package fields in `data/inventory.json` | Apache-2.0. The upstream license is retained in `licenses/Apache-2.0.txt`. Package software licenses listed in each record are separate from the registry license. |
18
+ | Homebrew formula fields in `data/inventory.json` | Formula metadata comes from Homebrew Core, whose repository is BSD-2-Clause. Formula software licenses are separate values. The upstream license is retained in `licenses/Homebrew-BSD-2-Clause.txt`. |
19
+
20
+ Sources and terms can change. Check `data/sources.json`, `data/source_state.json`,
21
+ and `THIRD_PARTY_NOTICES.md` before redistribution. This notice does not replace
22
+ the upstream licenses.
@@ -0,0 +1,25 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 coding-language-library contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ This license covers the project code and authored documentation. It does not
24
+ cover generated catalogue data or third-party material; see DATA-LICENSE.md and
25
+ THIRD_PARTY_NOTICES.md.
@@ -0,0 +1,14 @@
1
+ Metadata-Version: 2.5
2
+ Name: coding-language-library
3
+ Version: 0.3.1
4
+ Summary: Source-linked union of programming-language and tooling catalogues
5
+ License-File: DATA-LICENSE.md
6
+ License-File: LICENSE
7
+ License-File: THIRD_PARTY_NOTICES.md
8
+ License-File: licenses/Apache-2.0.txt
9
+ License-File: licenses/GitHub-Linguist-MIT.txt
10
+ License-File: licenses/Homebrew-BSD-2-Clause.txt
11
+ License-File: licenses/JetBrainsMono-OFL-1.1.txt
12
+ License-File: licenses/archify-v3.1.0-MIT.txt
13
+ License-File: licenses/archify-v3.1.0-THIRD-PARTY-NOTICES.md
14
+ Requires-Python: >=3.11
@@ -0,0 +1,103 @@
1
+ # coding-language-library
2
+
3
+ A source-linked union of programming-language identities and tool catalogues: broad discovery, structured identities, language-recognition metadata, and package availability. No one list defines the catalogue.
4
+
5
+ | Path | Contents |
6
+ | --- | --- |
7
+ | `data/inventory.json` | Canonical records with source identities, match evidence, package identifiers, and tools |
8
+ | `data/sources.json` | Source roles, terms, filters, and monitor endpoints |
9
+ | `data/source_state.json` | Last generated upstream revisions, validators, digests, and counts |
10
+ | `data/suitability_profiles.json` | Evidence-backed stack profiles linked to canonical language IDs |
11
+ | `data/task_profile.schema.json` | JSON Schema for the structured task profile |
12
+ | `data/wikipedia.json` | Supplemental discovery seed only |
13
+ | `data/discovery_candidates.json` | Seed candidates linked, ambiguous, or still discovery-only |
14
+ | `data/unresolved_matches.json` | Exact-key collisions and joins left unresolved |
15
+ | `data/adapters.json` | Adapter definition and the one tested pairing |
16
+ | `scripts/build_inventory.py` | Rebuilds the source union and snapshots |
17
+ | `scripts/monitor_sources.py` | Checks upstream revisions, validators, and content changes |
18
+ | `scripts/verify_inventory.py` | Checks identities, source counts, readiness, and generated totals |
19
+ | `mcp/server.py` | Read-only MCP interface |
20
+ | `mcp/task_matching.py` | Task-profile validation, hard-constraint checks, and weighted ranking |
21
+ | `SOURCES.md` | Source roles, monitoring cadence, and review cycle |
22
+ | `ARCHITECTURE.md` | System map and editable diagram |
23
+ | `DATA-LICENSE.md` | Code and dataset license boundaries |
24
+ | `SECURITY.md` | Supported version and private reporting route |
25
+ | `THIRD_PARTY_NOTICES.md` | Upstream license notices and bundled materials |
26
+
27
+ ## Use
28
+
29
+ Run the stdio MCP server from this checkout:
30
+
31
+ ```sh
32
+ uv run --python 3.11 --locked python mcp/server.py
33
+ ```
34
+
35
+ Without a checkout, run the packaged entry point from the git repository, or install the wheel and run `coding-language-library`:
36
+
37
+ ```sh
38
+ uvx --from git+https://github.com/johnjoners/coding-language-library coding-language-library
39
+ ```
40
+
41
+ Pin a tagged release when you want a fixed catalogue snapshot; the wheel bundles the data at build time:
42
+
43
+ ```sh
44
+ uvx --from git+https://github.com/johnjoners/coding-language-library@v0.3.1 coding-language-library
45
+ ```
46
+
47
+ Releases also ship to PyPI:
48
+
49
+ ```sh
50
+ uvx coding-language-library
51
+ ```
52
+
53
+ The server reads the committed JSON snapshots under `data/`, which are also bundled into the package. It makes no network requests, installs nothing, and does not launch language servers.
54
+
55
+ | Tool | Does |
56
+ | --- | --- |
57
+ | `search_index` | Searches identities, aliases, extensions, source IDs, package IDs, and linked tools |
58
+ | `list_shelf` | Pages the union, filtered by source coverage or recorded tooling |
59
+ | `get_language` | Returns one source-linked record with its tool and adapter evidence |
60
+ | `check_tools` | Checks recorded tool and Homebrew executable names against `PATH` |
61
+ | `recommend_stack` | Ranks recorded stacks against a caller-supplied task profile |
62
+ | `compare_candidates` | Compares chosen stack IDs against one profile, failed constraints included |
63
+ | `get_suitability_evidence` | Returns documented suitability claims and evidence for a language ID |
64
+
65
+ ## Task matching
66
+
67
+ `recommend_stack` and `compare_candidates` rank the recorded stacks in `data/suitability_profiles.json` against a task profile the caller fills in (`data/task_profile.schema.json`). The matcher never reads the `task` string, so a requirement left in prose is invisible to it.
68
+
69
+ | Profile field | Effect |
70
+ | --- | --- |
71
+ | `task` | Request text, validated for presence only; constraint terms named in it without a structured field are echoed in `unstructured_terms` on every result |
72
+ | `existing_project.languages` | +100 when a stack language matches |
73
+ | `existing_project.frameworks` | +60 when a stack framework matches |
74
+ | `team_experience` | +20 on a language or framework match |
75
+ | `priorities` | Position-weighted points, capped at 60, only where the profile records a supported signal with evidence |
76
+ | `target.platform` | Hard filter against the `platform.*` capability |
77
+ | `target.deployment` | Hard filter against the `deployment.*` capability |
78
+ | `requirements.required_integrations` | Hard filter per integration against `integration.*` |
79
+ | `requirements.memory_limit_mb` | Hard filter against the recorded `resources.memory_peak_mb` |
80
+ | `requirements.native_dependencies_allowed` | `false` fails a stack whose `dependencies.native` claim is `required` |
81
+
82
+ A stack is eliminated only by a recorded, contradicting claim. Constraints that are missing, unevidenced, or `supported_with_conditions` are listed as unknown in the result. Constraint terms named in the `task` text but not placed in a structured field are never parsed or applied; they are echoed in `unstructured_terms` so the caller can move them into the profile. `recommend_stack` drops failed stacks; `compare_candidates` keeps them so the failure stays visible. Ties share a rank. Each result carries its claims, conditions, HTTPS sources, a suggested next validation, and the profile's `unknowns` echoed as open questions.
83
+
84
+ Profiles are curated by hand: a small set of service stacks, grown only with reviewed evidence.
85
+
86
+ ## Identity and matching
87
+
88
+ Joins use stable IDs, published crosswalks, exact page links, exact names, and source-published aliases. Ambiguous joins stay separate and are counted in `data/unresolved_matches.json`. The Wikipedia list seeds discovery only; a candidate with no identity-source match never enters `data/inventory.json`.
89
+
90
+ ## Refresh and monitoring
91
+
92
+ ```sh
93
+ uv run --locked --group catalog python scripts/monitor_sources.py
94
+ uv run --locked --group catalog python scripts/harvest_wikipedia.py
95
+ uv run --locked --group catalog python scripts/build_inventory.py
96
+ uv run --locked --group catalog python scripts/verify_inventory.py
97
+ ```
98
+
99
+ A weekly workflow checks validators, content hashes, revisions, and entity digests. On a source change it rebuilds snapshots and opens a review pull request; a human reviews the data and source terms before merging, and the workflow never updates `main`. See [SOURCES.md](SOURCES.md) for the change signals and review process.
100
+
101
+ ## Terms
102
+
103
+ The root [MIT license](LICENSE) covers project code and authored documentation only. Generated data follows upstream terms. See [DATA-LICENSE.md](DATA-LICENSE.md) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
@@ -0,0 +1,15 @@
1
+ # Security Policy
2
+
3
+ ## Supported version
4
+
5
+ The latest tagged release is supported, and the latest commit on `main` for unreleased changes. Tagged releases bundle the `data/` snapshots at build time; the server reports its version in `initialize`.
6
+
7
+ ## Reporting a vulnerability
8
+
9
+ Use [GitHub private vulnerability reporting](https://github.com/johnjoners/coding-language-library/security/advisories/new). Do not report security issues in public issues or discussions. Include the affected version, steps to reproduce, and impact. No response-time guarantee is offered.
10
+
11
+ ## Runtime boundary
12
+
13
+ The MCP server reads committed JSON, serves stdio requests, and does not make network calls, write files, install packages, or launch language servers. `check_tools` calls `PATH` lookup and returns executable names and absolute paths; use it only with a trusted local MCP client.
14
+
15
+ The refresh workflow runs only from the default branch on a schedule or manual dispatch. It checks public upstream sources, rebuilds snapshots, runs verification, and opens a review pull request. It does not merge or publish data directly to `main`. Its repository token is limited to writing a refresh branch and pull request.
@@ -0,0 +1,33 @@
1
+ # Sources and refresh
2
+
3
+ The catalogue is the union of maintained language and tooling sources. A source
4
+ entry means that source lists or classifies a record; it does not establish that
5
+ the language is current, widely used, or compatible with a tool.
6
+
7
+ | Source | Use | Limits | Change signal | Cadence |
8
+ | --- | --- | --- | --- | --- |
9
+ | [PLDB](https://pldb.info/pldb.json) | Broad language discovery; published `id`, `aka`, Wikipedia, and Linguist crosswalks | Curated dataset, not a census. The public-domain statement is in its upstream README. | conditional HTTP validator; if it rotates, compare downloaded content SHA-256 with the snapshot | Weekly |
10
+ | [Wikidata](https://query.wikidata.org/sparql) | Stable QIDs, labels, aliases, language-class membership, and package identifiers | Community-edited claims can be incomplete or wrong. Membership uses `P31/P279* Q9143`. | Hash of distinct QIDs and each entity's `schema:dateModified` value; WDQS has no usable validator for this query | Weekly |
11
+ | [GitHub Linguist](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml) | GitHub-recognized language names, aliases, IDs, and extensions | GitHub detection scope, not a global usage ranking | conditional HTTP validator; compare content SHA-256 if it rotates | Weekly |
12
+ | [Mason Registry](https://github.com/mason-org/mason-registry) | Explicit language-tool package declarations and executables | Package listing does not prove installability or language compatibility | conditional HTTP validator; compare content SHA-256 if it rotates | Weekly |
13
+ | [Homebrew Core](https://formulae.brew.sh/api/formula.json) | Check formula names published by Wikidata and record executable names | Formula presence is not proof that a formula works on a particular host | conditional HTTP validator; compare content SHA-256 if it rotates | Weekly |
14
+ | [Wikipedia list](https://en.wikipedia.org/wiki/List_of_programming_languages) | Supplemental discovery candidates and recall check | Never creates canonical inventory records by itself | MediaWiki revision ID and timestamp | Weekly |
15
+
16
+ `data/sources.json` is the source registry. `data/source_state.json` records generated validators, revisions, content digests,
17
+ counts, and Wikidata entity IDs that the entity API did not return. The individual data
18
+ records retain source IDs and the matching rule. Exact identifiers, exact page
19
+ links, exact names, and source-published aliases are used; ambiguous matches are
20
+ kept separate and counted in `data/unresolved_matches.json`.
21
+
22
+ ## Review cycle
23
+
24
+ A weekly workflow checks conditional HTTP validators, source content digests, page revisions, and Wikidata entity digests. If any source content changes, it harvests Wikipedia as a supplemental seed, rebuilds snapshots, runs tests, and opens a pull request from `automated/source-refresh`. Review data changes, counts, unresolved joins, and license notices before merging. The workflow stops on check failure and never merges to `main`; unchanged content leaves snapshots untouched.
25
+
26
+ For a manual refresh:
27
+
28
+ ```sh
29
+ uv run --locked --group catalog python scripts/monitor_sources.py
30
+ uv run --locked --group catalog python scripts/harvest_wikipedia.py
31
+ uv run --locked --group catalog python scripts/build_inventory.py
32
+ uv run --locked --group catalog python scripts/verify_inventory.py
33
+ ```
@@ -0,0 +1,17 @@
1
+ # Third-party notices
2
+
3
+ ## Catalog data
4
+
5
+ See [DATA-LICENSE.md](DATA-LICENSE.md) for the scope and source-specific terms. Copies of applicable upstream license text are in `licenses/`.
6
+
7
+ ## Architecture export
8
+
9
+ `architecture/coding-language-library.architecture.html` is generated with Archify v3.1.0. The embedded renderer is distributed under the MIT terms in `licenses/archify-v3.1.0-MIT.txt`. The bundled font is JetBrains Mono under SIL Open Font License 1.1 in `licenses/JetBrainsMono-OFL-1.1.txt`. Archify's upstream third-party notices are retained in `licenses/archify-v3.1.0-THIRD-PARTY-NOTICES.md`.
10
+
11
+ ## Source metadata
12
+
13
+ - GitHub Linguist language data: MIT. License text: `licenses/GitHub-Linguist-MIT.txt`.
14
+ - Mason Registry package metadata: Apache-2.0. License text: `licenses/Apache-2.0.txt`.
15
+ - Homebrew Core formula metadata: BSD-2-Clause. License text: `licenses/Homebrew-BSD-2-Clause.txt`.
16
+
17
+ The source repositories and exact snapshot state are listed in `data/sources.json` and `data/source_state.json`. Product names and trademarks remain with their owners.