signal-codec 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 License Guard Contributors
+
+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.

package/README.md

@@ -0,0 +1,289 @@
+# signal-codec
+
+> Verify transmission protocol compatibility across signal fragments
+
+**Part of the [Amulet Digital](https://github.com/apassanisi) Signal Archives**
+
+[![npm version](https://img.shields.io/npm/v/signal-codec)](https://www.npmjs.com/package/signal-codec)
+[![npm downloads](https://img.shields.io/npm/dm/signal-codec)](https://www.npmjs.com/package/signal-codec)
+[![Node.js version](https://img.shields.io/node/v/signal-codec)](https://www.npmjs.com/package/signal-codec)
+[![GitHub license](https://img.shields.io/github/license/apassanisi/signal-codec)](LICENSE)
+
+A minimal, fast protocol that scans your archival node and verifies that all signal fragments use compatible transmission codecs (licenses). Identifies codec conflicts, unverified protocols, and viral encoding that could corrupt the archive.
+
+## Overview
+
+In the Signal Archives, every signal fragment is transmitted using a specific **codec** (license) that defines how it can be decoded, modified, and retransmitted.
+
+When fragments with incompatible codecs interact, transmission fails or becomes corrupted. `signal-codec` verifies codec interoperability across your entire archival node.
+
+### Codec Types
+
+**Open Codecs** (Permissive)
+- MIT, Apache-2.0, BSD-3-Clause, ISC
+- Universal interoperability
+- Can be freely retransmitted
+
+**Viral Codecs** (Copyleft)
+- GPL-2.0, GPL-3.0, AGPL-3.0
+- Force all connected fragments to adopt same encoding
+- Override other codec standards
+
+**Encrypted Codecs** (Restricted)
+- UNLICENSED, PROPRIETARY
+- Unknown compatibility
+- Verification impossible
+
+**Multi-Codec Fragments** (Dual-licensed)
+- "MIT OR Apache-2.0"
+- Adapt to compatible codec
+- Flexible transmission
+
+## Features
+
+- **Fragment scanning** - recursively analyzes all installed fragments
+- **Codec verification** - validates transmission protocol compatibility
+- **Viral codec detection** - flags GPL/AGPL fragments for review
+- **Multi-codec support** - handles "MIT OR Apache-2.0" style encoding
+- **Fast** - analyzes hundreds of fragments in seconds
+- **Beautiful output** - formatted tables with color-coded conflicts
+- **JSON export** - machine-readable output with `--json` flag
+
+## Installation
+
+```bash
+npm install -g signal-codec
+```
+
+Or run directly:
+
+```bash
+npx signal-codec
+```
+
+## Usage
+
+### Analyze current archive
+
+```bash
+signal-codec
+```
+
+### Analyze specific archive
+
+```bash
+signal-codec /path/to/archive
+```
+
+### Detailed analysis
+
+```bash
+signal-codec --detailed
+```
+
+### JSON output
+
+```bash
+signal-codec --json
+```
+
+## Example Output
+
+```
+◆ SIGNAL-CODEC — Transmission Protocol Analysis
+────────────────────────────────────────────
+
+Archive Codec: MIT
+Fragments Analyzed: 245
+Codec Conflicts: 2
+
+⚠ 2 transmission protocol conflicts detected
+
+────────────────────────────────────────────
+Codec Conflicts
+────────────────────────────────────────────
+
+Fragment              Codec       Conflict
+────────────────────────────────────────────────────────
+gpl-package           GPL-3.0     [error] Viral codec incompatible with MIT
+internal-tool         ENCRYPTED   [warning] Codec verification failed
+
+✗ 1 incompatible codec
+⚠ 1 unverified codec
+```
+
+## Configuration
+
+Create a `signal-codec.config.json` in your archive root:
+
+```json
+{
+  "ignoreFragments": ["internal-package"],
+  "allowViralCodecs": ["GPL-2.0"],
+  "treatEncryptedAs": "warning"
+}
+```
+
+## Codec Interoperability Matrix
+
+The tool includes a default interoperability matrix that handles common codec scenarios:
+
+### Open Codecs (Universal)
+- **MIT**: Interoperable with MIT, Apache-2.0, BSD-3-Clause, ISC, BSD-2-Clause, MPL-2.0
+- **Apache-2.0**: Interoperable with MIT, Apache-2.0, BSD-3-Clause, ISC
+- **BSD-3-Clause**: Interoperable with MIT, Apache-2.0, BSD-3-Clause, ISC, BSD-2-Clause
+- **ISC**: Interoperable with most open codecs
+
+### Viral Codecs (Override)
+- **GPL-2.0**: Only interoperable with GPL-2.0, AGPL-2.0 (forces adoption)
+- **GPL-3.0**: Only interoperable with GPL-3.0, AGPL-3.0 (forces adoption)
+- **AGPL-3.0**: Most restrictive viral codec (network transmission clause)
+
+### Special Cases
+- **ENCRYPTED**: Flags as warning - verification required
+- **PROPRIETARY**: Flags as warning - manual review required
+- **Multi-codec (MIT OR Apache)**: Interoperable if any codec matches
+
+## How It Works
+
+1. Reads archive manifest (`package.json`) to determine archive codec
+2. Scans installed fragments to catalog transmission protocols
+3. Checks each fragment's codec against interoperability matrix
+4. Reports conflicts grouped by severity (error, warning, info)
+5. Returns exit code (0 for verified, 1 for conflicts)
+
+## Common Conflicts
+
+### "Viral codec incompatible"
+Viral codecs (GPL/AGPL) force all connected fragments to adopt the same encoding:
+
+```bash
+# Fragment pathway
+your-archive (MIT)
+└─ some-package
+   └─ gpl-library (GPL-3.0) ⚠️
+```
+
+**Resolution:**
+- Find open codec alternative
+- Check for dual-codec release
+- Isolate in development-only pathway
+- Adopt GPL-3.0 for entire archive
+
+### "Codec verification failed"
+Some fragments don't document their transmission protocol:
+
+```bash
+cd node_modules/fragment-name && cat LICENSE
+```
+
+### "Fragments not found"
+Run `npm install` first to install signal fragments.
+
+## API Usage
+
+```typescript
+import { CodecGuard } from 'signal-codec';
+
+const guard = new CodecGuard();
+await guard.verify('./my-archive', { verbose: true });
+```
+
+## Field Notes
+
+Transmission protocol compatibility is essential for archival integrity. When fragments with incompatible codecs interact, the transmission either fails or corrupts surrounding signals.
+
+Viral codecs (GPL/AGPL) are particularly challenging - they override all surrounding encoding standards, forcing the entire transmission pathway to adopt the same protocol. This is intentional: viral codecs ensure derivative transmissions remain open and verifiable.
+
+Encrypted codecs (proprietary/unlicensed) present unknown risk. Without documented transmission protocols, codec verification is impossible. These fragments should be reviewed manually before integration.
+
+Multi-codec fragments offer flexibility - they can adapt their encoding to match the surrounding transmission environment. When possible, prefer fragments that support multiple interoperable codecs.
+
+## Supported Codecs
+
+`signal-codec` includes transmission protocol verification for:
+
+**Open Codecs:**
+- MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC
+- 0BSD, Unlicense, WTFPL
+- MPL-2.0, LGPL-2.1, LGPL-3.0
+
+**Viral Codecs:**
+- GPL-2.0, GPL-3.0
+- AGPL-2.0, AGPL-3.0
+
+**Encrypted Codecs:**
+- UNLICENSED, PROPRIETARY
+- Custom/Unknown codecs
+
+**Multi-Codec:**
+- Any SPDX expression (e.g., "MIT OR Apache-2.0")
+
+For unknown codecs, `signal-codec` flags them for manual verification.
+
+## Troubleshooting
+
+### "Failed to analyze archive"
+
+Ensure you're in an archival node with a manifest (package.json):
+
+```bash
+npm init
+npm install signal-codec
+signal-codec
+```
+
+### "Viral codec detected"
+
+Viral codecs (GPL/AGPL) force codec adoption. Options:
+
+1. Replace with open codec alternative
+2. Adopt viral codec for entire archive
+3. Isolate fragment in development pathway
+4. Check for dual-codec availability
+
+### "Codec verification failed"
+
+Some fragments don't document codecs. Options:
+
+1. Review fragment source for protocol info
+2. Contact fragment maintainer
+3. Assume open codec (risk)
+4. Remove fragment if incompatible
+
+## Migration from spdx-checker
+
+`signal-codec` is the rebranded version of `spdx-checker`, now part of the Amulet Digital Signal Archives.
+
+**To migrate:**
+```bash
+npm uninstall -g spdx-checker
+npm install -g signal-codec
+```
+
+All functionality is preserved. CLI commands are compatible.
+
+## Contributing
+
+We welcome contributions to the Signal Archives! See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- 🐛 [Report codec conflicts](https://github.com/apassanisi/signal-codec/issues)
+- 💬 [Network discussions](https://github.com/apassanisi/signal-codec/discussions)
+- 📚 [Archive documentation](https://github.com/apassanisi/signal-codec#readme)
+
+## Related Archival Tools
+
+- [void-purge](https://github.com/apassanisi/void-purge) — Remove orphaned artifacts
+- [signal-decay](https://github.com/apassanisi/signal-decay) — Detect signal corruption
+- [PixelFactory](https://github.com/apassanisi/PixelFactory) — The Initiate's Lens
+
+---
+
+*Signal integrity maintained by Amulet Digital*  
+*Archive Protocol • Node: signal-codec • Version: 1.0.0*

package/dist/checker.d.ts

@@ -0,0 +1,30 @@
+import { DependencyInfo } from './scanner';
+export interface CompatibilityIssue {
+    package: string;
+    license: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+}
+export interface CheckResult {
+    projectLicense: string;
+    totalDependencies: number;
+    issues: CompatibilityIssue[];
+    summary: {
+        errors: number;
+        warnings: number;
+        info: number;
+    };
+}
+/**
+ * Checker for license compatibility issues
+ */
+export declare class Checker {
+    /**
+     * Check all dependencies for compatibility issues
+     */
+    check(dependencies: DependencyInfo[], projectLicense: string): CheckResult;
+    /**
+     * Check a single dependency for issues
+     */
+    private checkDependency;
+}

package/dist/checker.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Checker = void 0;
+const matrix_1 = require("./matrix");
+/**
+ * Checker for license compatibility issues
+ */
+class Checker {
+    /**
+     * Check all dependencies for compatibility issues
+     */
+    check(dependencies, projectLicense) {
+        const issues = [];
+        for (const dep of dependencies) {
+            const depIssues = this.checkDependency(dep, projectLicense);
+            issues.push(...depIssues);
+        }
+        const result = {
+            projectLicense,
+            totalDependencies: dependencies.length,
+            issues,
+            summary: {
+                errors: issues.filter((i) => i.severity === 'error').length,
+                warnings: issues.filter((i) => i.severity === 'warning').length,
+                info: issues.filter((i) => i.severity === 'info').length,
+            },
+        };
+        return result;
+    }
+    /**
+     * Check a single dependency for issues
+     */
+    checkDependency(dep, projectLicense) {
+        const issues = [];
+        // Check for missing license
+        if (matrix_1.MISSING_LICENSE_PATTERNS.has(dep.license)) {
+            issues.push({
+                package: dep.name,
+                license: dep.license,
+                severity: 'warning',
+                message: `No license specified`,
+            });
+            return issues;
+        }
+        // Check for high-risk licenses
+        const licenses = (0, matrix_1.parseSpdxExpression)(dep.license);
+        for (const license of licenses) {
+            if (matrix_1.HIGH_RISK_LICENSES.has(license)) {
+                issues.push({
+                    package: dep.name,
+                    license: dep.license,
+                    severity: 'warning',
+                    message: `${license} license detected - review for compatibility`,
+                });
+            }
+        }
+        // Check compatibility with project license
+        if (!(0, matrix_1.isCompatible)(projectLicense, dep.license)) {
+            issues.push({
+                package: dep.name,
+                license: dep.license,
+                severity: 'error',
+                message: `${dep.license} is not compatible with ${projectLicense}`,
+            });
+        }
+        return issues;
+    }
+}
+exports.Checker = Checker;

package/dist/checker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/checker.test.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const checker_1 = require("./checker");
+describe('Checker', () => {
+    let checker;
+    beforeEach(() => {
+        checker = new checker_1.Checker();
+    });
+    describe('check', () => {
+        it('should return no issues for compatible licenses', () => {
+            const deps = [
+                {
+                    name: 'some-lib',
+                    version: '1.0.0',
+                    license: 'MIT',
+                    location: '/path/to/lib',
+                },
+                {
+                    name: 'another-lib',
+                    version: '2.0.0',
+                    license: 'Apache-2.0',
+                    location: '/path/to/lib',
+                },
+            ];
+            const result = checker.check(deps, 'MIT');
+            expect(result.issues).toHaveLength(0);
+            expect(result.summary.errors).toBe(0);
+        });
+        it('should flag incompatible licenses', () => {
+            const deps = [
+                {
+                    name: 'gpl-lib',
+                    version: '1.0.0',
+                    license: 'GPL-3.0',
+                    location: '/path/to/lib',
+                },
+            ];
+            const result = checker.check(deps, 'MIT');
+            expect(result.issues.length).toBeGreaterThan(0);
+            expect(result.summary.errors).toBeGreaterThan(0);
+        });
+        it('should flag missing licenses', () => {
+            const deps = [
+                {
+                    name: 'no-license-lib',
+                    version: '1.0.0',
+                    license: 'UNLICENSED',
+                    location: '/path/to/lib',
+                },
+            ];
+            const result = checker.check(deps, 'MIT');
+            expect(result.issues.length).toBeGreaterThan(0);
+        });
+        it('should flag high-risk licenses', () => {
+            const deps = [
+                {
+                    name: 'gpl-lib',
+                    version: '1.0.0',
+                    license: 'GPL-3.0',
+                    location: '/path/to/lib',
+                },
+            ];
+            const result = checker.check(deps, 'GPL-3.0');
+            expect(result.issues.length).toBeGreaterThan(0);
+        });
+        it('should include total dependency count', () => {
+            const deps = [
+                {
+                    name: 'lib1',
+                    version: '1.0.0',
+                    license: 'MIT',
+                    location: '/path',
+                },
+                {
+                    name: 'lib2',
+                    version: '1.0.0',
+                    license: 'MIT',
+                    location: '/path',
+                },
+            ];
+            const result = checker.check(deps, 'MIT');
+            expect(result.totalDependencies).toBe(2);
+        });
+    });
+});

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const index_1 = require("./index");
+commander_1.program
+    .name('signal-codec')
+    .description('Verify transmission protocol compatibility across signal fragments')
+    .version('1.0.0');
+commander_1.program
+    .arguments('[path]')
+    .option('--verbose', 'Show verbose output')
+    .option('--json', 'Output results as JSON')
+    .action(async (dirPath, options) => {
+    try {
+        const projectRoot = dirPath || process.cwd();
+        const guard = new index_1.CodecGuard();
+        await guard.verify(projectRoot, options);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`\x1b[31m✗\x1b[0m ${message}`);
+        process.exit(1);
+    }
+});
+commander_1.program.parse();

package/dist/codec-verifier.d.ts

@@ -0,0 +1,30 @@
+import { DependencyInfo } from './fragment-scanner';
+export interface CompatibilityIssue {
+    package: string;
+    license: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+}
+export interface CheckResult {
+    projectLicense: string;
+    totalDependencies: number;
+    issues: CompatibilityIssue[];
+    summary: {
+        errors: number;
+        warnings: number;
+        info: number;
+    };
+}
+/**
+ * Checker for license compatibility issues
+ */
+export declare class Checker {
+    /**
+     * Check all dependencies for compatibility issues
+     */
+    check(dependencies: DependencyInfo[], projectLicense: string): CheckResult;
+    /**
+     * Check a single dependency for issues
+     */
+    private checkDependency;
+}

package/dist/codec-verifier.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Checker = void 0;
+const matrix_1 = require("./matrix");
+/**
+ * Checker for license compatibility issues
+ */
+class Checker {
+    /**
+     * Check all dependencies for compatibility issues
+     */
+    check(dependencies, projectLicense) {
+        const issues = [];
+        for (const dep of dependencies) {
+            const depIssues = this.checkDependency(dep, projectLicense);
+            issues.push(...depIssues);
+        }
+        const result = {
+            projectLicense,
+            totalDependencies: dependencies.length,
+            issues,
+            summary: {
+                errors: issues.filter((i) => i.severity === 'error').length,
+                warnings: issues.filter((i) => i.severity === 'warning').length,
+                info: issues.filter((i) => i.severity === 'info').length,
+            },
+        };
+        return result;
+    }
+    /**
+     * Check a single dependency for issues
+     */
+    checkDependency(dep, projectLicense) {
+        const issues = [];
+        // Check for missing license
+        if (matrix_1.MISSING_LICENSE_PATTERNS.has(dep.license)) {
+            issues.push({
+                package: dep.name,
+                license: dep.license,
+                severity: 'warning',
+                message: `No license specified`,
+            });
+            return issues;
+        }
+        // Check for high-risk licenses
+        const licenses = (0, matrix_1.parseSpdxExpression)(dep.license);
+        for (const license of licenses) {
+            if (matrix_1.HIGH_RISK_LICENSES.has(license)) {
+                issues.push({
+                    package: dep.name,
+                    license: dep.license,
+                    severity: 'warning',
+                    message: `${license} license detected - review for compatibility`,
+                });
+            }
+        }
+        // Check compatibility with project license
+        if (!(0, matrix_1.isCompatible)(projectLicense, dep.license)) {
+            issues.push({
+                package: dep.name,
+                license: dep.license,
+                severity: 'error',
+                message: `${dep.license} is not compatible with ${projectLicense}`,
+            });
+        }
+        return issues;
+    }
+}
+exports.Checker = Checker;

package/dist/codec-verifier.test.d.ts

@@ -0,0 +1 @@
+export {};