Hello world

Author: andrew

.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: gomod
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
+    cooldown:
+      default-days: 7
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    cooldown:
+      default-days: 7

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions: {}
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        go-version: ['1.25']
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Go
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version: ${{ matrix.go-version }}
+          cache: false
+
+      - name: Build without CGo
+        run: go build -v ./...
+        env:
+          CGO_ENABLED: 0
+
+      - name: Test
+        run: go test -v -race -cover ./...
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Go
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version: '1.25'
+          cache: false
+
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v9
+        with:
+          version: latest

LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Andrew Nesbitt
+
+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.

NOTICE

@@ -0,0 +1,36 @@
+The content signature matching in signatures.go is adapted from
+src/net/http/sniff.go in Go 1.26.5. The original code is licensed as follows:
+
+Copyright 2009 The Go Authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google LLC nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The adapted matching rules come from the pattern-matching algorithm and the
+rules for identifying unknown MIME types in sections 6 and 7 of the WHATWG
+MIME Sniffing Standard:
+
+https://mimesniff.spec.whatwg.org/

README.md

@@ -0,0 +1,100 @@
+# magic
+
+Pure Go content detection for files and bounded file prefixes. The package
+reports a physical format, MIME type, text encoding, and whether a prefix needs
+more bytes. It has no CGO, native runtime, filesystem, or third-party module
+dependency.
+
+## Install
+
+```bash
+go get github.com/git-pkgs/magic
+```
+
+## Use
+
+`Detect` treats its byte slice as the complete file:
+
+```go
+result := magic.Detect(data)
+
+switch result.Kind {
+case magic.KindText:
+	fmt.Println(result.Format, result.MIME, result.Encoding)
+case magic.KindBinary:
+	fmt.Println(result.Format, result.MIME)
+case magic.KindUnknown:
+	fmt.Println(result.Reason)
+}
+```
+
+Call `DetectPrefix` when the bytes came from a bounded read:
+
+```go
+result := magic.DetectPrefix(prefix)
+if result.Reason == magic.ReasonNeedMore {
+	// More bytes could change the result.
+}
+```
+
+A complete binary signature can finish detection from a prefix. Text remains
+provisional because later bytes can contain a NUL, an invalid encoding, or a
+binary signature. `NeedBytes` is reserved for a known minimum total length and
+is zero in the first release.
+
+Both functions are safe for concurrent use. They retain no input and use no
+mutable package state.
+
+## Results
+
+`Kind` is `text`, `binary`, or `unknown`. `Format` and `MIME` describe the
+physical content. `Encoding` is set for accepted UTF-8, UTF-16LE, or UTF-16BE
+text and never appears as a MIME charset parameter.
+
+The first format registry contains:
+
+- ZIP, TAR, gzip, bzip2, xz, PDF, CFBF, PNG, JPEG, and GIF
+- plain text, HTML, XML, and SVG
+
+Detection uses bytes only. ZIP-based package types such as JAR, wheel, and
+NuGet remain `zip`, and compressed payloads are not opened. A caller can
+combine the result with filename or domain rules when it needs a semantic
+type.
+
+Text accepts valid UTF-8 and BOM-marked UTF-16. Tab, line feed, form feed,
+carriage return, and escape are the permitted C0 controls. Other C0 controls
+classify the input as binary. Invalid UTF-8 without a NUL is unknown with
+`ReasonInvalidText`; callers that need Latin-1 can apply their own fallback.
+
+HTML, XML, and SVG signatures supply format metadata before the shared text
+rules run. The metadata remains present if malformed or control-bearing input
+is classified as unknown or binary.
+
+## Performance
+
+The detector performs no allocations for the supplied fixtures. On an Apple
+M1 Pro with Go 1.26.5, a 4 KiB text input takes about 1.5 microseconds, the
+mixed 4 KiB fixture corpus averages about 0.77 microseconds per call, and a
+1 MiB text input takes about 0.35 milliseconds. Importing and calling the
+package adds 16,640 bytes to a stripped minimal binary.
+
+Run the package benchmarks on the target machine:
+
+```bash
+go test -run '^$' -bench . -benchmem
+```
+
+The implementation scans at most 512 bytes for registered signatures. Text
+validation is linear in the supplied byte count and uses fixed auxiliary
+memory.
+
+## Provenance
+
+The signature matcher is adapted from Go 1.26.5's
+`net/http.DetectContentType` and the WHATWG MIME Sniffing Standard. The
+registry is intentionally limited to the formats listed above. [NOTICE](NOTICE)
+contains the source and license details.
+
+## License
+
+MIT

benchmark_test.go

@@ -0,0 +1,74 @@
+package magic
+
+import (
+	"bytes"
+	"testing"
+)
+
+var benchmarkResult Result
+
+var benchmarkText1MiB = bytes.Repeat([]byte{'x'}, 1<<20)
+
+var benchmarkCorpus = [][]byte{
+	padFixture([]byte("package magic\n\nfunc Detect(data []byte) Result { return Result{} }\n")),
+	padFixture([]byte("\xef\xbb\xbfUnicode text: héllo, 世界\n")),
+	padFixture([]byte("<?xml version=\"1.0\"?><svg >")),
+	padFixture([]byte("PK\x03\x04")),
+	padFixture([]byte("\x89PNG\r\n\x1a\n")),
+	padFixture([]byte{0xff}),
+}
+
+func BenchmarkDetect4KiBText(b *testing.B) {
+	input := benchmarkCorpus[0]
+	b.ReportAllocs()
+	b.SetBytes(int64(len(input)))
+	b.ResetTimer()
+	for range b.N {
+		benchmarkResult = Detect(input)
+	}
+}
+
+func BenchmarkDetect4KiBCorpus(b *testing.B) {
+	b.ReportAllocs()
+	b.SetBytes(4096)
+	b.ResetTimer()
+
+	index := 0
+	for range b.N {
+		benchmarkResult = Detect(benchmarkCorpus[index])
+		index++
+		if index == len(benchmarkCorpus) {
+			index = 0
+		}
+	}
+}
+
+func BenchmarkDetect4KiBParallel(b *testing.B) {
+	input := benchmarkCorpus[0]
+	b.ReportAllocs()
+	b.SetBytes(int64(len(input)))
+	b.RunParallel(func(parallel *testing.PB) {
+		var result Result
+		for parallel.Next() {
+			result = Detect(input)
+		}
+		benchmarkResult = result
+	})
+}
+
+func BenchmarkDetect1MiBText(b *testing.B) {
+	input := benchmarkText1MiB
+	b.ReportAllocs()
+	b.SetBytes(int64(len(input)))
+	b.ResetTimer()
+	for range b.N {
+		benchmarkResult = Detect(input)
+	}
+}
+
+func padFixture(prefix []byte) []byte {
+	if len(prefix) >= 4096 {
+		return prefix[:4096]
+	}
+	return append(bytes.Clone(prefix), bytes.Repeat([]byte{'x'}, 4096-len(prefix))...)
+}

example_test.go

@@ -0,0 +1,23 @@
+package magic_test
+
+import (
+	"fmt"
+
+	"github.com/git-pkgs/magic"
+)
+
+func ExampleDetect() {
+	result := magic.Detect([]byte("package main\n"))
+	fmt.Println(result.Kind, result.Format, result.MIME, result.Encoding)
+
+	// Output:
+	// text text text/plain utf-8
+}
+
+func ExampleDetectPrefix() {
+	result := magic.DetectPrefix([]byte("hello"))
+	fmt.Println(result.Kind, result.Reason)
+
+	// Output:
+	// text need-more
+}