diff-grok 1.1.0 → 1.2.0

package/.claude/skills/license-updater/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: license-updater
+description: >
+  Update and manage third-party license attribution when porting code from
+  external libraries. Use this skill whenever the user mentions porting,
+  translating, or adapting code from another library (e.g. C/C++/Python to
+  TypeScript/JavaScript), asks to add license headers to source files, needs
+  to create or update a THIRD_PARTY_LICENSES file, or wants to ensure proper
+  license compliance for derived works. Also trigger when the user provides
+  a link to or local path of an upstream library and a folder of ported code
+  and asks about licensing. Keywords: license, attribution, port, third-party,
+  copyright, THIRD_PARTY_LICENSES, license header, BSD, MIT, Apache, derived
+  work.
+---
+
+# License Updater
+
+A skill for maintaining proper license attribution when incorporating
+third-party code — especially code ported from one language to another.
+
+## When to use
+
+- User provides a **source library URL or local path** and a **folder with ported files**
+- User asks to "add license headers", "update THIRD_PARTY_LICENSES", or
+  "set up licensing for ported code"
+- User mentions porting/translating code from an external project
+
+## Inputs
+
+The user provides two things:
+
+1. **Source library URL or local path** — a GitHub (or similar) link to the
+   upstream project whose code was ported, or a local filesystem path to a
+   cloned/downloaded copy of the library.
+   Examples: `https://github.com/sdwfrost/liblsoda`, `src/solver-tools/cvode-7.5.0`
+2. **Ported files path** — a path (relative to the repo root) to the folder
+   containing the ported TypeScript (or other language) files.
+   Example: `src/solver-tools/lsoda`
+
+The user may optionally provide:
+- The **repo root URL** or local path to their own project
+- The **target project's license** (if not, discover it from the repo)
+
+## Workflow
+
+Follow these steps in order:
+
+### Step 1: Discover upstream license
+
+If the user provided a **URL**, use `web_fetch` to open the source library URL.
+If the user provided a **local path**, read files directly from the filesystem.
+
+Look for:
+
+1. A `LICENSE` or `COPYING` file in the repository root
+2. License badges or mentions in the README
+3. SPDX identifiers in `package.json`, `setup.py`, `Cargo.toml`, etc.
+4. Copyright headers inside source files (especially the main source file)
+
+Identify:
+- **License type** (MIT, BSD-2-Clause, BSD-3-Clause, Apache-2.0, etc.)
+- **Copyright holders** — every `Copyright (c)` line you find
+- **Provenance chain** — if the upstream code itself was derived from earlier
+  work, trace the chain (e.g., Fortran → C → C refactoring → shared library)
+
+If the license is unclear, tell the user and ask for clarification before
+proceeding.
+
+### Step 2: Check compatibility
+
+Verify that the upstream license is compatible with the target project's
+license. Read `references/compatibility.md` for the compatibility matrix.
+
+If there is a compatibility issue, **stop and inform the user** with a clear
+explanation of the conflict and possible remedies.
+
+### Step 3: Discover target project structure
+
+If the user provided a repo URL, fetch it to understand the existing layout.
+Look for:
+- Existing `LICENSE` file
+- Existing `THIRD_PARTY_LICENSES` or `NOTICES` file
+- Existing copyright headers in files
+
+### Step 4: Generate artifacts
+
+Produce exactly three outputs. Use the script at
+`scripts/generate_license_files.py` to generate them:
+
+```bash
+python3 /path/to/skill/scripts/generate_license_files.py \
+  --license-type "<SPDX identifier, e.g. MIT>" \
+  --copyright-holders "<semicolon-separated list>" \
+  --project-name "<upstream project name>" \
+  --project-url "<upstream project URL>" \
+  --ported-files-path "<relative path in target repo>" \
+  --target-copyright "<target project copyright line>" \
+  --provenance "<semicolon-separated provenance chain>" \
+  --output-dir "/home/claude/license-output"
+```
+
+The script creates three files in the output directory:
+
+1. **`THIRD_PARTY_LICENSES`** — standalone file for the repo root documenting
+   upstream license and provenance
+2. **`HEADER_TEMPLATE.txt`** — comment block to prepend to each ported file
+3. **`LICENSE_GUIDE.md`** — human-readable instructions explaining what to do
+
+If the script is unavailable or doesn't fit the situation, generate the files
+manually following the templates in `references/templates.md`.
+
+### Step 5: Update the README License section
+
+If the project has a `README.md` (or `README.MD`), update its **License**
+section to mention the third-party code and link to `THIRD_PARTY_LICENSES`.
+
+Rules:
+- Look for an existing `## License` heading in the README
+- If one exists, **append** a line about the ported code beneath the existing
+  license statement — do not remove anything already there
+- If there is no License section, add one at the end of the README (before
+  any final "Contributing" or similar section)
+- Keep it concise: one sentence identifying the ported component, its upstream
+  source, and a link to the `THIRD_PARTY_LICENSES` file
+- Use the template from `references/templates.md` → "README License section"
+
+### Step 6: Present results
+
+1. Give a brief summary:
+   - What license was found
+   - Whether it's compatible
+   - What files were created or modified (THIRD_PARTY_LICENSES, headers,
+     README)
+
+## Important rules
+
+- **Never modify the target project's main LICENSE file** unless the user
+  explicitly asks. The main LICENSE covers the project as a whole.
+- **Always preserve the full original license text** in THIRD_PARTY_LICENSES.
+  Don't paraphrase or abbreviate license texts.
+- **Include ALL copyright holders** from the upstream chain, not just the
+  most recent one.
+- **If the upstream repo contains multiple licenses** (e.g., dual-licensed),
+  note all of them and ask the user which applies.
+- If the target project already has a THIRD_PARTY_LICENSES file, **append**
+  a new section rather than overwriting.
+- The header template should be concise (under 15 lines) — point to
+  THIRD_PARTY_LICENSES for full details rather than embedding the entire
+  license in every file.

package/.claude/skills/license-updater/references/compatibility.md

@@ -0,0 +1,68 @@
+# License Compatibility Matrix
+
+Quick reference for whether an upstream license is compatible with common
+target project licenses. "Compatible" means the ported code can be included
+in a project under the target license.
+
+## Permissive → Permissive (almost always OK)
+
+| Upstream        | Target: MIT | Target: BSD-2 | Target: BSD-3 | Target: Apache-2.0 |
+|-----------------|:-----------:|:-------------:|:-------------:|:------------------:|
+| MIT             | ✅          | ✅            | ✅            | ✅                 |
+| BSD-2-Clause    | ✅          | ✅            | ✅            | ✅                 |
+| BSD-3-Clause    | ✅          | ✅            | ✅            | ✅                 |
+| Apache-2.0      | ✅*         | ✅*           | ✅*           | ✅                 |
+| ISC             | ✅          | ✅            | ✅            | ✅                 |
+| Zlib            | ✅          | ✅            | ✅            | ✅                 |
+| Unlicense       | ✅          | ✅            | ✅            | ✅                 |
+
+*Apache-2.0 has a patent grant clause. When including Apache-2.0 code in a
+non-Apache project, the patent grant still applies to that code. This is
+generally fine but worth noting.
+
+## Copyleft → Permissive (usually NOT OK)
+
+| Upstream        | Target: MIT | Target: BSD | Target: Apache-2.0 |
+|-----------------|:-----------:|:-----------:|:------------------:|
+| GPL-2.0-only    | ❌          | ❌          | ❌                 |
+| GPL-3.0-only    | ❌          | ❌          | ❌                 |
+| LGPL-2.1        | ⚠️*         | ⚠️*         | ⚠️*                |
+| LGPL-3.0        | ⚠️*         | ⚠️*         | ⚠️*                |
+| MPL-2.0         | ⚠️**        | ⚠️**        | ⚠️**               |
+| AGPL-3.0        | ❌          | ❌          | ❌                 |
+
+*LGPL allows linking but not incorporating source code into a permissive
+project without the LGPL applying to the modified files.
+
+**MPL-2.0 is file-level copyleft: the ported files themselves must stay
+under MPL-2.0, but the rest of the project can be permissive.
+
+## What "compatible" means in practice
+
+For permissive licenses (MIT, BSD, Apache, ISC, Zlib):
+- Keep the original copyright notice and license text
+- Include them in a THIRD_PARTY_LICENSES file
+- Add attribution headers to ported files
+- The overall project can use any license
+
+For copyleft (GPL, LGPL, AGPL):
+- Generally cannot include in a permissive project
+- The copyleft license would need to apply to the derivative work
+- STOP and inform the user about the conflict
+
+## Special conditions by license type
+
+### BSD-3-Clause
+Extra requirement: cannot use the names of copyright holders or contributors
+to endorse or promote the derived product without written permission.
+
+### Apache-2.0
+- Includes explicit patent grant
+- Requires NOTICE file preservation if one exists upstream
+- Must state significant changes made to ported files
+
+### MIT
+Minimal requirements: preserve copyright notice and license text.
+
+### ISC
+Functionally equivalent to MIT. Same requirements.

package/.claude/skills/license-updater/references/templates.md

@@ -0,0 +1,151 @@
+# License File Templates
+
+Use these templates when the generation script is unavailable or the situation
+requires custom formatting.
+
+## THIRD_PARTY_LICENSES
+
+```
+Third-Party Licenses
+====================
+
+This file documents the licenses for third-party code included in or adapted
+by this project.
+
+
+================================================================================
+{PROJECT_NAME}
+================================================================================
+
+Source:       {PROJECT_URL}
+License:      {SPDX_IDENTIFIER}
+Files:        {PORTED_FILES_PATH}
+
+{DESCRIPTION_OF_WHAT_WAS_PORTED}
+
+{PROVENANCE_CHAIN — if the code has a history of forks/rewrites, list each
+step with author and license}
+
+{FULL_ORIGINAL_LICENSE_TEXT — copy verbatim, do not paraphrase}
+```
+
+When appending to an existing THIRD_PARTY_LICENSES file, add a new section
+starting from the `====` separator line. Do not modify existing sections.
+
+## Header template (for TypeScript / JavaScript files)
+
+```typescript
+/**
+ * {BRIEF_DESCRIPTION — one line saying what this code does}
+ *
+ * {PORT_DESCRIPTION — e.g. "TypeScript port of {project} ({url})"}
+ * {ORIGINAL_ALGORITHM_CREDIT — if applicable}
+ *
+ * {ORIGINAL_COPYRIGHT_LINES — one per line, all of them}
+ * {TARGET_COPYRIGHT_LINE}
+ *
+ * Licensed under the {SPDX_IDENTIFIER} License. See THIRD_PARTY_LICENSES
+ * for the full license text and provenance chain of the original code.
+ */
+```
+
+### Header guidelines
+
+- Keep under 15 lines total
+- Include ALL original copyright holders
+- Reference THIRD_PARTY_LICENSES instead of embedding the full license
+- For BSD-3-Clause, do NOT include the full "neither the name..." clause
+  in the header — the THIRD_PARTY_LICENSES file covers this
+
+## Header template (for Python files)
+
+```python
+# {BRIEF_DESCRIPTION}
+#
+# {PORT_DESCRIPTION}
+# {ORIGINAL_ALGORITHM_CREDIT}
+#
+# {ORIGINAL_COPYRIGHT_LINES}
+# {TARGET_COPYRIGHT_LINE}
+#
+# Licensed under the {SPDX_IDENTIFIER} License. See THIRD_PARTY_LICENSES
+# for the full license text and provenance chain.
+```
+
+## Header template (for C / C++ files)
+
+```c
+/*
+ * {BRIEF_DESCRIPTION}
+ *
+ * {PORT_DESCRIPTION}
+ * {ORIGINAL_ALGORITHM_CREDIT}
+ *
+ * {ORIGINAL_COPYRIGHT_LINES}
+ * {TARGET_COPYRIGHT_LINE}
+ *
+ * Licensed under the {SPDX_IDENTIFIER} License. See THIRD_PARTY_LICENSES
+ * for the full license text and provenance chain.
+ */
+```
+
+## README License section
+
+Add the following beneath the existing license statement in the project's
+`README.md`. If the README has no `## License` section yet, create one.
+
+```markdown
+## License
+
+This project is licensed under the [{TARGET_LICENSE}]({LICENSE_FILE_PATH}).
+
+{PORTED_COMPONENT_DESCRIPTION} is a {LANGUAGE} port of
+[{PROJECT_NAME}]({PROJECT_URL}).
+See [THIRD_PARTY_LICENSES](./THIRD_PARTY_LICENSES) for details on third-party
+code provenance.
+```
+
+### README License guidelines
+
+- Keep it to 2–3 sentences maximum
+- Always link to both the main `LICENSE` file and `THIRD_PARTY_LICENSES`
+- Name the specific component that was ported (e.g., "The LSODA solver")
+- Name the upstream project and link to it
+- If multiple third-party components exist, list each on its own line
+
+## LICENSE_GUIDE.md
+
+```markdown
+# License Attribution Guide
+
+## Overview
+
+This guide explains how to properly attribute the third-party code ported
+into this project from [{PROJECT_NAME}]({PROJECT_URL}).
+
+## Files to add/modify
+
+### 1. `THIRD_PARTY_LICENSES` → repo root
+
+{Explain: new file or append to existing}
+
+### 2. Header in each ported file → `{PORTED_FILES_PATH}/*.{ext}`
+
+{Show the header template}
+
+### 3. `LICENSE` → no changes needed
+
+{Explain why the main license stays as-is}
+
+### 4. `README` → optional update
+
+{Suggest a license section addition if appropriate}
+
+## License compatibility
+
+Upstream: {UPSTREAM_LICENSE}
+Target:   {TARGET_LICENSE}
+Status:   ✅ Compatible / ❌ Incompatible
+
+{Brief explanation of compatibility and any special conditions}
+```